FCM INVALID_ARGUMENT (400): Bad Token or Bad Payload? How to Tell and Fix It

Your FCM send fails with 400 INVALID_ARGUMENT. This one is confusing because it covers two very different problems: a bad device token, or a bad message. Deleting the token fixes the first and silently loses users in the second. Here's how to tell which one you have.

Two kinds of INVALID_ARGUMENT

A bad token. The message is fine, but the token isn't a valid FCM registration token:

{
  "error": {
    "code": 400,
    "message": "The registration token is not a valid FCM registration token",
    "status": "INVALID_ARGUMENT",
    "details": [
      {
        "@type": "type.googleapis.com/google.firebase.fcm.v1.FcmError",
        "errorCode": "INVALID_ARGUMENT"
      }
    ]
  }
}

A bad message. The token may be fine, but a field in the request is wrong. FCM usually names the field in the message, or in a google.rpc.BadRequest entry in details:

{
  "error": {
    "code": 400,
    "message": "Invalid JSON payload received. Unknown name \"title\" at 'message': Cannot find field.",
    "status": "INVALID_ARGUMENT"
  }
}

The quick test: send the same payload to a fresh token from a test phone. If it works, the failing token is the problem. If it also fails, the payload is.

Common payload mistakes

This request has two of the most common ones:

{
  "message": {
    "token": "DEVICE_TOKEN",
    "title": "Order shipped",
    "data": { "orderId": 1234, "express": true }
  }
}

• title directly under message. It belongs in message.notification (or in data if your app shows the notification itself).
• Non-string values in data. Every value in data must be a string, so 1234 and true fail.

Fixed:

{
  "message": {
    "token": "DEVICE_TOKEN",
    "notification": { "title": "Order shipped", "body": "Arriving tomorrow" },
    "data": { "orderId": "1234", "express": "true" }
  }
}

Other causes worth checking:

• The payload is too big. FCM limits the message size, roughly 4 KB for most messages. Send an ID and fetch the details in the app instead of sending large data.
• Reserved keys in data. Keys such as from, or keys starting with google or gcm, are reserved. Rename them.
• Invalid platform fields. For example a badly formatted android.ttl (it's a duration string like "600s"), or an unknown key inside android or apns.
• No target, or more than one. A message needs exactly one of token, topic or condition.

The free FCM payload builder builds a valid HTTP v1 message for Android and iOS, which is a quick way to rule the payload in or out.

In the Firebase Admin SDK for Node.js

• A server-side INVALID_ARGUMENT arrives as messaging/invalid-argument, with FCM's explanation in the error message.
• A non-string data value never reaches FCM. The SDK throws messaging/invalid-payload with the message “data must only contain string values”.

Log the full error message, not just the code. The message is what tells you which field to fix.

When to delete the token

Firebase lists INVALID_ARGUMENT as a sign of an invalid token, but only when you're sure the payload is valid. A safe rule:

1. If the message says the registration token is not valid, and the same payload works for other tokens, delete the token.
2. If many tokens fail at once with the same message, it's the payload. Don't delete anything.
3. If the token looks cut short or has extra characters, fix how you store it. Save it exactly as the app received it.

For tokens that are definitely gone, see FCM UNREGISTERED: Requested entity was not found. If the error is a 403 instead, it's likely SENDER_ID_MISMATCH.

On notifySphere

When you send from the notifySphere dashboard, the FCM message is built for you, so you don't write this JSON by hand. Its React Native and Flutter SDKs register the device token for you.

Frequently asked questions