FCM rejects the message with INVALID_ARGUMENT
INVALID_ARGUMENTShort answer
INVALID_ARGUMENT is HTTP 400: FCM did not accept the request parameters. The response names the bad field in a BadRequest detail. The usual causes are a malformed token, a reserved key in data, a package name that does not match the token, or a wrongly typed field. Validate the message with a dry run.
Fix it fast
1Find out which cause you have
Send the same message with the dry run flag. It validates the request without delivering it, and the error carries the field that failed.
try { await getMessaging().send(message, true); // true = dryRun } catch (e) { console.error(e.code, e.message); }2Match what you see, then jump to its fix
- 1
The error points at a data keyA reserved word is used as a key in dataFix - 2
Only Android targets fail, and the message sets android.restricted_package_nameThe restricted package name does not match the app that owns the tokenFix - 3
The error points at token, or you set token and topic togetherThe token is malformed, or more than one target is setFix
- 1
What does the error look like?
INVALID_ARGUMENTHTTP 400 from fcm.googleapis.com/v1/projects/PROJECT_ID/messages:send
Cause 1 of 3
A reserved word is used as a key in data
1Check
The message reference says a data key must not be from, message_type, or any word starting with google. or gcm.notification.
console.log(Object.keys(message.data ?? {}));2Fix
Rename the key. Keep values UTF-8 text.
data: { order_id: '1042', kind: 'shipped' } // not "from" or "google.xyz"3Verify
Run the dry run again.
await getMessaging().send(message, true);Confirmed by firebase.google.com
Cause 2 of 3
The restricted package name does not match the app that owns the token
1Check
The reference says the registration token must match the package named in restricted_package_name. Compare it with the applicationId in your Gradle file.
grep -n applicationId app/build.gradle*2Fix
Use the real applicationId, or remove restricted_package_name if you do not need it.
android: { restrictedPackageName: 'com.example.app' } // must equal applicationId3Verify
Dry run again with a token from that build.
await getMessaging().send(message, true);Confirmed by firebase.google.com
Cause 3 of 3
The token is malformed, or more than one target is set
1Check
Exactly one target (token, topic or condition) may be set, and a topic name must not carry the /topics/ prefix.
console.log(Object.keys(message).filter(k => ['token','topic','condition'].includes(k)));2Fix
Send one target per message, and pass the topic name without /topics/.
{ topic: 'weather', notification: { title: 'Rain', body: 'Take an umbrella' } }3Verify
Dry run again.
await getMessaging().send(message, true);Confirmed by firebase.google.com
How do I stop it coming back?
- Run new payload shapes through the dry run in tests.
- Delete a stored token on INVALID_ARGUMENT only after the payload has passed a dry run, because the same code can mean a bad payload.
- Keep one function that builds messages, so key names live in one place.
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 says the token is not found when you send a push
UNREGISTERED
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.
2 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