FCM UNREGISTERED Error: Requested Entity Was Not Found, and How to Fix It

Your push send returns 404 UNREGISTERED, “Requested entity was not found” or messaging/registration-token-not-registered. The message didn't fail because of your payload: FCM is telling you that device token no longer works. The fix is to delete it, and to stop dead tokens building up.

What the error looks like

This is the response from the FCM HTTP v1 API:

{
  "error": {
    "code": 404,
    "message": "Requested entity was not found.",
    "status": "NOT_FOUND",
    "details": [
      {
        "@type": "type.googleapis.com/google.firebase.fcm.v1.FcmError",
        "errorCode": "UNREGISTERED"
      }
    ]
  }
}

The Firebase Admin SDK for Node.js reports the same thing as messaging/registration-token-not-registered. Other SDKs have their own names for it, so check the errorCode or the SDK's docs rather than matching the message text.

Why a token stops working

• The app was uninstalled, or the token was invalidated on the device.
• The token was replaced. Tokens can change, for example after a reinstall or when your app calls deleteToken(), and your server may still hold the old one.
• The token expired. On Android, Firebase treats a registration as expired after 270 days of inactivity.
• APNs rejected the token on iOS. Firebase relies on APNs there, so an invalid APNs token can surface as the same error.
• The token string was changed. A token that was cut short or altered when stored can fail, so save it exactly as you received it.

How to fix it

1. Delete the token when FCM says it's dead. Check each result in a batch, because one bad token doesn't fail the others.
2. Don't retry it. Retries only waste sends. Save retries for temporary errors.
3. Send the new token to your server. Upload it on app start and whenever it refreshes.
4. Store a timestamp with each token, and update it on every upload, so you can see which ones are stale.
5. Remove stale tokens on a schedule. Firebase's default definition of stale is more than a month without connecting to FCM, and it suggests refreshing tokens about once a month. Choose a window that suits your app.

Here's step 1 with the Firebase Admin SDK for Node.js:

import { getMessaging } from "firebase-admin/messaging";

const TOKEN_IS_DEAD = "messaging/registration-token-not-registered";

export async function sendToTokens(tokens, notification) {
  const result = await getMessaging().sendEachForMulticast({ tokens, notification });

  const deadTokens = [];
  result.responses.forEach((response, i) => {
    if (!response.success && response.error?.code === TOKEN_IS_DEAD) {
      deadTokens.push(tokens[i]);
    }
  });

  // Your own function: delete these tokens from your database
  await removeTokens(deadTokens);
}

When it's a different FCM error

Only delete tokens for the errors that call for it. These need a different fix:

You can build a valid test message with the free FCM payload builder, which helps rule out the payload.

If almost every token fails at once

A few dead tokens are normal, because people uninstall apps. If most of your tokens suddenly fail, look for a shared cause before you delete anything:

• Did you change Firebase projects or service accounts recently?
• Did your code start altering tokens when it stores or reads them?
• Can you get a fresh token from a test device and send to it?
• Does the FCM status dashboard show a problem?

Pause any automatic cleanup while you check, so a bug on your side doesn't wipe good tokens. If a fresh token also fails and your setup looks right, contact Firebase support.

On notifySphere

The notifySphere React Native SDK re-registers a device when its FCM token changes, and logout() unsubscribes the device and deletes its token when someone signs out. For the iOS setup error that often comes before this one, see No APNS token specified before fetching FCM token.

Frequently asked questions