FCM says the token is not found when you send a push
Requested 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.
Fix it fast
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); }2Match what you see, then jump to its fix
What does the error look like?
Requested entity was not found.UNREGISTEREDHTTP 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
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
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:
- WorkforceA field app, an admin console and a self-hosted Node.js server for push and reconciliation.
- TaxiDexMy own multi-tenant taxi dispatch SaaS: API, dispatcher portal, driver and passenger apps, and the servers underneath.
- SessionBirdAn omnichannel engagement suite in Flutter: campaigns, chatbot, tickets, analytics and live calling.
Related fixes
Mobile apps
FCM rejects the message with INVALID_ARGUMENT
HTTP 400 from fcm.googleapis.com/v1/projects/PROJECT_ID/messages:send
INVALID_ARGUMENT is HTTP 400: FCM did not accept the request parameters.
3 causes, each with a fixMobile apps
Push sending broke because the server still uses the legacy FCM API
Console notice that the legacy Firebase Cloud Messaging API is deprecated
Sends that still use the legacy FCM API (a server key in the Authorization header) or old Admin SDK methods need to move to the HTTP v1 API.
3 causes, each with a fixMobile 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 fixMobile apps
FirebaseInstanceIdService and FirebaseInstanceId.getToken() no longer work
Deprecation warning on FirebaseInstanceId.getInstance().getToken()
Move token handling into a class that extends FirebaseMessagingService and override onNewToken, which runs when a token is first created and whenever it changes.
2 causes, each with a fixMobile apps
Logcat warns that FCM has no default notification channel in AndroidManifest
Notification does not appear on Android 8 and later
This is a warning, not a crash.
3 causes, each with a fixMobile apps
FCM cannot reach an iPhone: APNs or web push credentials rejected
HTTP 401 when sending to an iOS registration token
THIRD_PARTY_AUTH_ERROR is HTTP 401.
2 causes, each with a fix