FirebaseMessagingError: Requested entity was not found. 해결 방법

Firebase Cloud Messaging (FCM)을 사용할 때 다음과 같은 오류를 만난다면:

FirebaseMessagingError: Requested entity was not found.

혹은 오류 코드가 다음과 같이 표시될 수도 있습니다:

messaging/registration-token-not-registered

이 오류는 FCM 등록 토큰이 유효하지 않거나 혹은 만료되었거나 아니면 해당 토큰의 등록이 해제되었다는 것을 의미합니다.
이 문제가 발생하면 푸시 알림이 사용자에게 전달되지 않아서 사용자 입장에서 알림이 오지 않아 불편을 겪을수 있습니다.

🔍 가능한 원인 및 해결 방법

1️⃣ FCM 토큰이 유효하지 않거나 만료됨

FCM 토큰은 영구적이지 않으며 시간이 지나면 만료될 수 있습니다.
그렇기 때문에 데이터베이스에 저장된 토큰 중 일부는 이미 너무 오래되어 사용이 불가능 한 토큰들 일수도 있습니다.

✅ 해결 방법:

푸시 알림을 보낼 때 유효하지 않은 토큰을 확인 후 삭제하세요.
앱이 시작될 때 최신 FCM 토큰을 가져와 저장하세요.

자동으로 FCM 토큰 갱신하는 코드

firebase.messaging().onTokenRefresh((newToken) => {
  // 새로운 토큰을 서버로 전송하여 데이터베이스 업데이트
});

2️⃣ 사용자의 기기에서 토큰이 등록 해제됨

FCM 토큰은 다음과 같은 경우에 등록 해제될 수 있습니다:

사용자가 앱을 삭제한 경우
앱을 재설치하여 새로운 토큰이 생성된 경우
사용자가 로그아웃하여 앱이 토큰을 삭제한 경우
클라이언트에서 토큰을 명시적으로 삭제한 경우

✅ 해결 방법:

토큰이 갱신되면 해당 토큰을 데이터베이스에 업데이트합니다.
유효하지 않은 토큰의 경우는 해당 토큰을 데이터베이스에서 삭제합니다.

만료된 토큰을 데이터베이스에서 제거하는 코드

async function sendPushNotification(token: string, message: any) {
  try {
    await admin.messaging().send({ token, ...message });
  } catch (error) {
    if (error.code === 'messaging/registration-token-not-registered') {
      console.log('유효하지 않은 토큰입니다. DB에서 삭제:', token);
      await deleteTokenFromDB(token); // 유효하지 않은 토큰을 삭제하는 함수
    }
  }
}

3️⃣ 잘못된 토큰 형식

FCM 토큰이 데이터베이스에 저장될 때 토큰이 잘리거나 해당 토큰을 실수로 수정하게 되면 Firebase에서 거부 당할 수 있습니다.

✅ 해결 방법:

토큰이 올바르게 저장되었는지 확인하세요.
푸시 알림을 보내기 전에 토큰을 로그로 출력해 확인해보세요.

토큰이 올바르게 저장되었는지 디버깅하는 코드

console.log('FCM Token:', token); // 유효한 문자열인지 확인

4️⃣ 잘못된 Firebase 설정

Firebase Admin SDK 설정이 잘못되었을 경우, FCM이 정상적인 토큰임에도 불구하고 거부할 수 있습니다.

✅ 해결 방법:

올바른 Firebase Admin SDK JSON 파일을 사용하세요.
Firebase 서비스가 정확한 인증 정보로 실행되고 있는지 확인이 필요합니다.

올바른 Firebase Admin SDK 설정 코드

import * as admin from 'firebase-admin';

admin.initializeApp({
  credential: admin.credential.cert(require('./firebase-service-account.json')),
});

5️⃣ 앱 알림 권한이 비활성화됨

사용자가 디바이스 설정에서 알림을 비활성화하면, FCM이 해당 토큰을 무효화할 수 있습니다.

✅ 해결 방법:

앱에서 사용자가 해당 앱의 알림에 대한 권한을 부여했는지 확인하세요.

알림 권한을 확인하는 코드

const status = await messaging().requestPermission();
if (status !== 'granted') {
  console.log('알림이 비활성화되어 있습니다.');
}

🚀 최종 디버깅 체크리스트

FCM 토큰이 유효한지 확인
- Firebase Cloud Messaging을 통해 직접 테스트해보세요.
푸시 알림 전송 전에 토큰 값을 로그로 확인
- 올바른 형식인지, 잘려 있지 않은지 확인하세요.
만료된 토큰을 자동으로 삭제
- messaging/registration-token-not-registered 오류가 발생하면 즉시 DB에서 삭제하세요.
Firebase Admin SDK 설정 확인
- 올바른 firebase-service-account.json 파일을 사용하고 있는지 검토하세요.

✅ FCM 토큰 관리 최적화 방법

유효한 FCM 토큰만 저장하세요.
앱이 시작될 때 토큰을 갱신 및 업데이트하세요.
오류가 발생하면 만료된 토큰을 삭제하세요.
푸시 알림 로그를 모니터링하여 문제가 발생하기 전에 미리 확인하세요.

위 방법을 따르면 푸시 알림의 신뢰성을 높이고 FCM 토큰 오류를 최소화할 수 있습니다.

추가 질문이 있으신가요? 댓글로 남겨주세요! 🚀

웹개발의 모든 것

이 블로그 검색

웹개발 시장 전망 (프리랜서, 취업, 연봉)