Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Flutter and app store releases

FCM says the token is not found when you send a push

ErrorRequested entity was not found.

Short answer

The FCM HTTP v1 API returns UNREGISTERED with HTTP 404 when the app instance behind a token is gone: the app was uninstalled, the token expired, the client unregistered, or the token you pass is empty. Check what you actually send, then delete dead tokens from your database and stop sending to them.

  • Applies to FCM HTTP v1, firebase-admin Node.js 13, Node.js 22
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 1Find out which cause you have

    Catch the error and print its code and the token you sent. The code decides which cause applies, and an empty or undefined token is visible at once.

    try {
      await getMessaging().send({ token, notification: { title: 'Hi', body: 'Test' } });
    } catch (e) {
      console.error(e.code, e.message, 'token=', token);
    }
  2. 2Match what you see, then jump to its fix

    1. 1The log shows token= undefined, an empty string, or a value cut short by your own codeThe token is empty or was never saved correctlyFix
    2. 2UNREGISTERED for one user while other users receive the same messageThe app was uninstalled, the user cleared its data, or the token expiredFix

What does the error look like?

  • Requested entity was not found.
  • UNREGISTERED
  • HTTP 404 from fcm.googleapis.com/v1/projects/PROJECT_ID/messages:send

Cause 1 of 2

The token is empty or was never saved correctly

1Check

The error reference lists a missing registration token among the reasons for UNREGISTERED. Print the value read from your database right before the send call.

console.log('sending to', JSON.stringify(token), 'length', token?.length);

2Fix

Fix the code path that stores or reads the token (wrong field name, a trimmed string, a document that has no token yet) and skip users that have no token.

if (!token) return; // nothing to send to
await getMessaging().send({ token, notification: { title, body } });

3Verify

Send to a token copied straight from a fresh app start; the request should now return a message id.

console.log(await getMessaging().send({ token, notification: { title: 'Hi', body: 'Test' } }));

Confirmed by firebase.google.com

Did this fix it?

Cause 2 of 2

The app was uninstalled, the user cleared its data, or the token expired

1Check

A token is tied to one app instance. The error reference says the cause may be an uninstalled app, an expired token, or a client that unregistered. FCM also treats a registration as stale after a month without contact, and marks Android registrations expired after 270 days of inactivity.

# compare the token's last refresh time in your own storage
SELECT user_id, token_updated_at FROM push_tokens WHERE token = '...';

2Fix

When the error code is UNREGISTERED, delete that token from your server and stop sending to it. The client will give you a new one the next time the app opens, so upload tokens again on every start and on onNewToken.

try {
  await getMessaging().send(message);
} catch (e) {
  if (String(e.message).includes('Requested entity was not found')) {
    await db.collection('tokens').doc(token).delete();
  }
}

3Verify

Send again after the user reopens the app; the new token should succeed and the old one should be gone from the table.

SELECT count(*) FROM push_tokens WHERE token = '...';

Confirmed by firebase.google.com

Did this fix it?

How do I stop it coming back?

  • Store a timestamp with every token and refresh it each time the app uploads its token.
  • Run a scheduled job that removes tokens that were not refreshed within your own window.
  • Delete a token only on UNREGISTERED. INVALID_ARGUMENT can also mean the payload is wrong, so check the payload before deleting.
  • Log the error code, not only the message text.

Sources

How was this page made?

I drafted this page with AI assistance from the official documents listed under Sources. Every cause above names the document that confirms it. I have not reproduced this fix on a machine of my own yet, so read it as documented guidance, not a test report. Found a mistake? Tell me.

Which stack is behind this page?

Projects of mine built on the same technologies:

Related fixes

Mobile apps

The iOS push arrives from FCM but plays no sound

A custom sound name in the payload is ignored and nothing plays

iOS plays a sound for a remote notification only when the aps payload has a sound key and the app is allowed to play sounds.

3 causes, each with a fix

Next step

Want this handled for good?

I look after servers, apps and releases end to end. Tell me what keeps breaking.