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

What does FCM UNREGISTERED mean?

It means the app instance is no longer registered with Firebase Cloud Messaging, so that token usually won't work again. Firebase's advice is to remove the token and stop sending to it. The app gets a new token the next time it registers.

Is registration-token-not-registered the same as UNREGISTERED?

Yes, for practical purposes. UNREGISTERED is the error code from the FCM HTTP v1 API, usually with a 404 and the message "Requested entity was not found." messaging/registration-token-not-registered is how the Firebase Admin SDK for Node.js reports it.

Should I retry a message that failed with UNREGISTERED?

No. Retrying won't bring the token back. Retry 429, 500 and 503 errors with backoff instead, and delete tokens that return UNREGISTERED.

Do FCM tokens expire?

On Android, Firebase treats a registration as expired after 270 days of inactivity. On iOS and other platforms it relies on the underlying push service, which doesn't have that limit, so Firebase recommends removing stale tokens yourself. Its default definition of stale is no connection to FCM for over a month.

Does UNREGISTERED mean the user uninstalled the app?

Often, but not always. It can also follow an app update, a token refresh, or your app deleting its token. Treat it as a dead token, not as proof of an uninstall, especially if you use it to measure uninstalls.

Originally published on the notifySphere blog. notifySphere is push notifications, WhatsApp Business API, deep linking, and in-app support in one SDK — free up to 1,000 users.

What the error looks like

The FCM HTTP v1 API returns a 403 with the error code in the details:

{
  "error": {
    "code": 403,
    "status": "PERMISSION_DENIED",
    "details": [
      {
        "@type": "type.googleapis.com/google.firebase.fcm.v1.FcmError",
        "errorCode": "SENDER_ID_MISMATCH"
      }
    ]
  }
}

Firebase's description: the authenticated sender ID is different from the sender ID for the registration token. A token is tied to the senders of the project the app used when it registered, and only those senders can use it.

Common causes

• Dev and production projects are mixed up. The app was built with the dev google-services.json or GoogleService-Info.plist, while the server uses the production service account, or the other way round. Build flavors and schemes make this easy to miss.
• You moved to a new Firebase project. Old installs still hold tokens from the old project.
• The server uses the wrong key file. A service account key from another project, or a project ID in the send URL that doesn't match the key.
• Several apps share one server. Tokens from apps in different projects are stored together and sent with one set of credentials.

How to find the mismatch

Compare the project the app uses with the project the server uses:

# Android app: the sender ID is the project number
google-services.json  ->  project_info.project_number
                          project_info.project_id

# iOS app
GoogleService-Info.plist  ->  GCM_SENDER_ID
                              PROJECT_ID

# Your server: the project in the service account key and the send URL
service-account.json  ->  project_id
POST https://fcm.googleapis.com/v1/projects/<project_id>/messages:send

1. Open the config file that is actually bundled in the build that produced the token.
2. Note its project ID and sender ID (on Android the sender ID is the project_number).
3. Check the project_id in the server's service account key and in the send URL.
4. They must all point to the same Firebase project.

A quick test: install a fresh build on a test phone, copy its token, and send to it from the project in that build's config file. If that works, the setup is fine and the failing tokens belong to another project.

How to fix it

1. Send with the matching project. Use the service account and project ID that match the app's config file.
2. Store the project with each token. If you run several apps or environments, save which project a token came from and choose credentials per send.
3. After a project move, let tokens refresh. Ship the build with the new config, upload the new token on app start, and keep sending to old tokens from the old project until users update.
4. Don't bulk-delete tokens on this error. Firebase's clean-up advice is for UNREGISTERED and, when the payload is valid, INVALID_ARGUMENT. Deleting on a mismatch can wipe tokens that work fine with the right project.

You can build a valid test message with the free FCM payload builder, so the payload isn't in question while you test.

Related errors

• UNREGISTERED (404): the token is no longer valid. Delete it. See FCM UNREGISTERED: Requested entity was not found.
• THIRD_PARTY_AUTH_ERROR (401): the APNs key or certificate in Firebase is missing or invalid.
• On iOS, if you send to APNs directly, a token sent to the wrong environment returns BadDeviceToken.

On notifySphere

notifySphere sends through FCM with the Firebase credentials you add for each app, so each app's devices are sent with that app's project. The React Native and Flutter SDKs register the device for you.

Frequently asked questions

What does FCM SENDER_ID_MISMATCH mean?

Firebase describes it as: the authenticated sender ID is different from the sender ID for the registration token. In practice, the token was created by an app connected to one Firebase project, and your server is sending with credentials from another project.

Is messaging/mismatched-credential the same error?

Yes. The Firebase Admin SDK for Node.js reports SENDER_ID_MISMATCH as messaging/mismatched-credential, with a message saying the credential doesn't have permission to send to that token.

Should I delete tokens that return SENDER_ID_MISMATCH?

Not as a first step. Firebase's token clean-up advice covers UNREGISTERED and, with a valid payload, INVALID_ARGUMENT. A mismatch usually means your server is using the wrong project, so the tokens may be fine for the right one. Fix the credentials, then retry.

Why did SENDER_ID_MISMATCH start after I moved to a new Firebase project?

Tokens are tied to the project the app registered with. Existing installs keep their old tokens until they run a build connected to the new project and register again. Until then, sending to those tokens from the new project fails with SENDER_ID_MISMATCH.

Can one server send to apps in two Firebase projects?

Yes, but each send must use credentials and a project ID that match the token's project. Keep the project with each stored token and pick the matching credentials when you send. Firebase also documents authorizing a service account from a different project.

Originally published on the notifySphere blog. notifySphere is push notifications, WhatsApp Business API, deep linking, and in-app support in one SDK — free up to 1,000 users.

What the error means

On iOS, getting a push token is a two-step handoff:

1. Your app registers with Apple Push Notification service (APNs), and iOS gives it an APNs token.
2. Firebase exchanges that APNs token for an FCM token, which your server uses to send pushes.

If your code calls getToken() before step 1 has finished, or step 1 fails silently, Firebase has nothing to exchange and throws this error. The exact wording depends on your stack:

// React Native Firebase
[messaging/unknown] No APNS token specified before fetching FCM Token

// Flutter (firebase_messaging)
[firebase_messaging/apns-token-not-set] APNS token has not been set yet.

// Native iOS log
APNS device token not set before retrieving FCM Token for Sender ID '…'

Quick checklist

• Push Notifications capability is added in Xcode under Signing & Capabilities.
• Background Modes → Remote notifications is enabled.
• You're testing on a real iPhone, not the simulator.
• The app registers for remote notifications before calling getToken().
• If method swizzling is off, the AppDelegate passes the APNs token to Firebase.

1. Add the Push Notifications capability

Open ios/YourApp.xcworkspace in Xcode, select your app target, go to Signing & Capabilities and add Push Notifications and Background Modes (tick Remote notifications). This adds the aps-environment entitlement. Without it, iOS refuses to issue an APNs token and you get this error every time. If you sign with a manual provisioning profile, regenerate it after enabling push.

2. Fix the call order in React Native

React Native Firebase registers for remote messages automatically by default, but if your code asks for the token very early at launch, it can run before registration completes. Request permission, make sure the device is registered, then fetch the token:

import messaging from "@react-native-firebase/messaging";

export async function getFcmToken() {
  // 1. Ask for permission (shows the iOS prompt)
  await messaging().requestPermission();

  // 2. Make sure the device is registered with APNs first
  if (!messaging().isDeviceRegisteredForRemoteMessages) {
    await messaging().registerDeviceForRemoteMessages();
  }

  // 3. Only now ask Firebase for the FCM token
  return messaging().getToken();
}

If you set messaging_ios_auto_register_for_remote_messages to false in firebase.json, the registerDeviceForRemoteMessages() call above is required.

3. Wait for the APNs token in Flutter

In Flutter, getToken() fails with apns-token-not-set when the APNs token hasn't arrived yet. Check getAPNSToken() first and give it a moment on first launch:

final messaging = FirebaseMessaging.instance;
await messaging.requestPermission();

// The APNs token can arrive a moment after launch, so wait for it
String? apnsToken = await messaging.getAPNSToken();
for (var i = 0; apnsToken == null && i < 5; i++) {
  await Future.delayed(const Duration(seconds: 1));
  apnsToken = await messaging.getAPNSToken();
}

if (apnsToken != null) {
  final fcmToken = await messaging.getToken();
  // send fcmToken to your server
}

Also listen to FirebaseMessaging.instance.onTokenRefresh, so you still capture the token if it arrives after your retries.

4. Pass the token yourself if swizzling is disabled

Firebase normally intercepts the APNs token through method swizzling. If your Info.plist sets FirebaseAppDelegateProxyEnabled to NO, which some apps do to avoid conflicts with other SDKs, you have to hand the token over manually:

// AppDelegate.swift — needed when FirebaseAppDelegateProxyEnabled is NO
func application(_ application: UIApplication,
                 didRegisterForRemoteNotificationsWithDeviceToken deviceToken: Data) {
  Messaging.messaging().apnsToken = deviceToken
}

func application(_ application: UIApplication,
                 didFailToRegisterForRemoteNotificationsWithError error: Error) {
  print("APNs registration failed: \(error)")
}

The failure callback is worth adding either way. If registration fails, it tells you why, usually a missing entitlement.

5. Test on a real device

APNs registration on the iOS Simulator is unreliable, even on setups that can display simulated pushes. If the error only appears in the simulator, try a real iPhone before changing any code.

Skip the token plumbing

The notifySphere React Native SDK registers the device with APNs before it requests the FCM token, so this ordering problem doesn't come up. It also tracks delivery and taps for every notification. Setting up the Apple side for the first time? Follow the Firebase iOS push guide for the APNs key and capabilities, or the Flutter push guide.

Frequently asked questions

What does “No APNS token specified before fetching FCM Token” mean?

On iOS, Firebase Cloud Messaging needs the device's APNs token from Apple before it can create an FCM token. The error means your app asked Firebase for the FCM token before iOS had delivered the APNs token, or iOS never delivered one at all.

Does this error happen on Android?

No. Android doesn't use APNs, so FCM tokens are issued directly. The error is specific to iOS (and macOS) apps using Firebase Messaging.

Can I get an APNs token on the iOS Simulator?

Support is limited. Recent Xcode versions on Apple silicon Macs can deliver remote notifications to the simulator, but registration is still unreliable there. Test push notifications on a real iPhone to rule the simulator out.

I uploaded my APNs key to Firebase. Why do I still get this error?

The APNs key in the Firebase console is used when Firebase sends a push to Apple. This error happens earlier, on the device, when the app registers with APNs. Check the Push Notifications capability, the provisioning profile and the order of your calls instead.

How do I know if APNs registration failed?

Implement application(_:didFailToRegisterForRemoteNotificationsWithError:) in your AppDelegate and log the error. The most common message is a missing aps-environment entitlement, which means the Push Notifications capability or provisioning profile is wrong.

Originally published on the notifySphere blog. notifySphere is push notifications, WhatsApp Business API, deep linking, and in-app support in one SDK — free up to 1,000 users.