Maaz Zindani

Loading the index…

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

FCM rejects the message with INVALID_ARGUMENT

ErrorINVALID_ARGUMENT

Short 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.

  • 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

    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);
    }
  2. 2Match what you see, then jump to its fix

    1. 1The error points at a data keyA reserved word is used as a key in dataFix
    2. 2Only Android targets fail, and the message sets android.restricted_package_nameThe restricted package name does not match the app that owns the tokenFix
    3. 3The error points at token, or you set token and topic togetherThe token is malformed, or more than one target is setFix

What does the error look like?

  • INVALID_ARGUMENT
  • HTTP 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

Did this fix it?

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 applicationId

3Verify

Dry run again with a token from that build.

await getMessaging().send(message, true);

Confirmed by firebase.google.com

Did this fix it?

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

Did this fix it?

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:

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 fix

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.