Introduction

Firebase Cloud Messaging (FCM) registration token errors are usually symptoms of a broken relationship between an app installation, an FCM project, and the server sending messages. A token can be valid for a period of time and then change, expire, become associated with a different Firebase project, or stop representing an active installation.

The right fix depends on where the failure occurs. A token may fail while the client is registering, when your server sends a message, or when FCM accepts a request but cannot deliver it. Treating every failure as “generate a new token” can hide configuration problems and create duplicate device records.

This guide provides a practical way to identify the cause, repair the registration flow, and keep your token database accurate.

First, identify the failure stage

Start by recording the complete error, the app platform, the app build or environment, and whether the problem affects one token or many. The stage usually narrows the diagnosis quickly.

  • Client registration failure: the app cannot obtain or refresh an FCM token.
  • Send request failure: your server receives an error when calling FCM.
  • Delivery failure: the send is accepted, but the message is not delivered to the device.
  • Intermittent failure: some installations work while others fail, often because of token age, app environments, or inconsistent project configuration.

Do not log full tokens in normal application logs. A token is not generally a secret equivalent to a password, but it is still an identifier for an app installation. Redact it, hash it for correlation, or store only a short diagnostic suffix.

Common server-side FCM errors

The error name and HTTP response are more useful than a generic “push failed” message. Preserve the provider response in structured logs, together with your internal device ID and notification ID.

UNREGISTERED or not registered

This normally means the token is no longer valid. The app may have been uninstalled, the token may have been rotated, or the installation may no longer exist in the expected form. Remove or disable the token after the provider confirms this condition. Do not repeatedly retry it indefinitely.

If the user opens the app again, the client should register its current token and re-enable the installation. Deleting a failed token immediately is safe when your data model supports a history or a disabled state; it is less safe when deletion removes useful identity or preference data.

INVALID_ARGUMENT

This can indicate an invalid token, malformed message data, an unsupported field combination, or a request that does not meet FCM’s schema requirements. Check that the token is the intended value, that the message structure matches the API you are using, and that data values meet the relevant platform constraints.

A useful test is to send a minimal notification to one known-current token. If the minimal request works, add your optional fields one at a time. This separates token problems from payload problems.

SENDER_ID_MISMATCH

This indicates that the sender or Firebase project making the request does not match the project associated with the registration token. Common causes include using credentials from one Firebase project with a token created by another, mixing staging and production installations, or retaining an old application configuration in a released build.

Check all of the following:

  • The Android application identifier or iOS bundle identifier is the intended one.
  • The client build uses the correct Firebase configuration file for its environment.
  • The server credential belongs to the same Firebase project that issued the token.
  • Staging tokens cannot accidentally enter the production send queue.
  • A test device has not retained data from an earlier project configuration.

Generating another token will not repair a project mismatch. Correct the environment and credential mapping first.

UNAUTHENTICATED or PERMISSION_DENIED

These errors concern server authentication and authorisation rather than the device token. Confirm that the credential is valid, the required API is enabled where applicable, and the sending identity has permission to send through the selected Firebase project. Also check whether a deployment is using an outdated secret or the wrong environment variable.

Avoid printing credentials while diagnosing this problem. Rotate a credential if it may have been exposed, and use a controlled test request after the configuration has been corrected.

QUOTA_EXCEEDED or rate-related errors

A quota or rate error is not fixed by refreshing tokens. Apply bounded retries with exponential backoff and jitter, reduce unnecessary sends, and inspect whether a loop is repeatedly targeting invalid registrations. Keep provider throttling separate from permanent token failures so that one does not trigger the other’s handling path.

Repair the client registration flow

The client must treat the FCM token as changeable state, not as a permanent property of the user. Register the token when the app starts or reaches the appropriate authenticated state, and handle token refresh events supplied by the platform SDK.

A robust flow should:

  • Obtain the current token using the platform’s supported FCM client API.
  • Send the token to your application server over an authenticated connection.
  • Associate it with an installation record and, where appropriate, a user record.
  • Update the record whenever the token changes.
  • Record the app platform, app version, environment, and last-seen time.
  • Make the registration operation idempotent.

Registration should be safe to repeat. The same installation sending the same token several times must update one record rather than create several active subscriptions. If a token changes, mark the old token inactive or replace it according to your data model.

Do not assume that uninstalling and reinstalling is the only reason a token changes. Token rotation, application restore, security events, platform behaviour, and changes to the app’s push configuration can all require the client to report a new value.

Check permissions and platform configuration

A valid FCM token does not guarantee that a user will see a notification. On iOS, the user’s notification authorisation and the app’s push capabilities must be configured correctly. On Android, notification permission applies on supported recent versions, and notification channels can affect whether a notification is visible or how it behaves. Web Push also depends on browser permission, a service worker, and the correct application configuration.

These are separate checks from token validity. When a message is accepted but not visible, inspect:

  • Whether the user has granted notification permission.
  • Whether the app is using the expected Firebase project and configuration.
  • Whether the relevant service worker or native notification setup is present.
  • Whether the notification channel is enabled and has suitable importance.
  • Whether foreground handling deliberately displays or processes the message.
  • Whether the payload uses notification and data fields in a way supported by the target platform.

Test foreground, background, terminated, and permission-denied states separately. A result in one state does not prove that the others are configured correctly.

Keep the token database healthy

Token hygiene is a data problem as much as a messaging problem. Store provider-specific tokens with an installation record, rather than treating a token as the user’s permanent identity. A user can have several active devices, and a single device can have several historical tokens.

Useful fields include the provider, platform, environment, token value or protected representation, installation identifier, user association, first-seen time, last-seen time, last-successful-send time, and disabled reason.

When FCM reports an unregistered token, disable it and retain enough history to diagnose future registrations. When a send succeeds, update its last-successful-send time. Use a scheduled cleanup policy for records that have been inactive for a long period, but do not use age alone as proof that a token is invalid.

If you use a notification platform alongside direct FCM sending, keep the ownership model clear. HoneyNotify server-side sends use POST /v1/notifications with a Bearer API key and an Idempotency-Key; a notification requires a title, body, and target. Its client SDKs cover device registration, identity, token lifecycle, payload handling, and lifecycle events across iOS, Android, and Web Push. The same principle applies: registration and token refresh must be handled by the client, while the server should remove or disable confirmed-invalid registrations.

A safe retry and recovery strategy

Separate errors into permanent, temporary, and configuration categories.

  • Permanent token errors: disable the token and wait for a future client registration.
  • Temporary provider errors: retry with bounded exponential backoff and jitter.
  • Authentication or project errors: stop the affected send path and alert an operator.
  • Payload errors: correct the request before retrying.

Use an idempotency key or equivalent send identifier so that a retry does not unintentionally create duplicate notifications. Store the provider response and your own attempt number. A retry queue should have a maximum age and a dead-letter path for messages requiring investigation.

For large audiences, avoid sending the same invalid token repeatedly. Batch processing should remove or suppress a token as soon as a permanent failure is confirmed, while allowing other recipients in the batch to proceed.

Common mistakes

Treating every error as a stale token

A project mismatch, bad credential, or malformed payload will not be fixed by requesting a new token. Classify the error first.

Linking tokens only to users

Users change phones, use multiple devices, and may sign out. Model installations separately so that signing out one device does not remove another device’s registration.

Ignoring token refresh callbacks

An app that registers only on first launch will eventually send to an obsolete token. Handle refresh events and submit the current token whenever the app’s identity or environment changes.

Mixing staging and production data

Use explicit environment fields and separate credentials. Never infer the environment only from a token string.

Retrying permanent failures forever

This wastes quota, increases latency, and obscures genuine incidents. Disable confirmed-invalid tokens and rely on the next client registration to restore delivery.

A practical diagnostic checklist

  • Capture the exact provider error and response status.
  • Identify whether the failure is client-side, send-side, or delivery-side.
  • Confirm the token belongs to the intended platform and environment.
  • Verify Firebase project, application configuration, and server credential alignment.
  • Test one current token with a minimal payload.
  • Confirm notification permissions and platform-specific display settings.
  • Handle token refresh and make registration idempotent.
  • Disable confirmed-invalid tokens and retain a diagnostic history.
  • Apply bounded retries only to temporary failures.
  • Monitor success, permanent failures, temporary failures, and registration freshness separately.

Conclusion

FCM registration token errors become manageable when token validity, project configuration, permissions, payloads, and delivery are diagnosed as separate concerns. Build a registration flow that updates tokens, a send path that classifies provider errors, and a data model that can disable stale installations without losing user identity. This reduces repeated failures and gives your team a clear recovery path when tokens inevitably change.