Maaz Zindani

Loading the index…

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

Push sending broke because the server still uses the legacy FCM API

ErrorPush sending from your server or a Cloud Function stopped working

Short answer

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. Post to the v1 messages:send URL with a short-lived OAuth token, or let the Admin SDK do that: initialise it with service account credentials and call send or sendEach.

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

Fix it fast

  1. 1Find out which cause you have

    Search your server and functions code for the old calls. Whatever this finds is what has to change.

    grep -rn -E "fcm/send|sendToDevice|sendMulticast|sendAll|Authorization.*key=" --include=*.js --include=*.ts --include=*.php --include=*.py .
  2. 2Match what you see, then jump to its fix

    1. 1The grep finds a fcm/send URL or an Authorization: key= headerThe code posts to the legacy endpoint with a server keyFix
    2. 2The grep finds sendToDevice, sendMulticast or sendAllThe Admin SDK code uses methods from the old APIFix
    3. 3The v1 URL and body are right, yet the request is refused as unauthenticatedThe access token was minted without the messaging scope or from the wrong credentialsFix

What does the error look like?

  • Push sending from your server or a Cloud Function stopped working
  • Console notice that the legacy Firebase Cloud Messaging API is deprecated

Cause 1 of 3

The code posts to the legacy endpoint with a server key

1Check

The HTTP v1 API uses a different URL and a short-lived OAuth 2.0 access token minted from a service account, not a static key.

grep -rn "fcm.googleapis.com" .

2Fix

Send a POST to https://fcm.googleapis.com/v1/projects/PROJECT_ID/messages:send with Authorization: Bearer <access token> (scope https://www.googleapis.com/auth/firebase.messaging) and a body that wraps everything in a top-level message object.

POST https://fcm.googleapis.com/v1/projects/PROJECT_ID/messages:send
Authorization: Bearer ACCESS_TOKEN
Content-Type: application/json

{ "message": { "token": "DEVICE_TOKEN", "notification": { "title": "Hi", "body": "Test" } } }

3Verify

The response is a JSON object with the message name.

# expected: { "name": "projects/PROJECT_ID/messages/..." }

Confirmed by firebase.google.com

Did this fix it?

Cause 2 of 3

The Admin SDK code uses methods from the old API

1Check

The current Admin SDK Messaging class lists send, sendEach and sendEachForMulticast as its sending methods. The Admin SDK handles authorization itself.

npm ls firebase-admin

2Fix

Replace the old calls: send for one message, sendEach for up to 500 different messages, sendEachForMulticast for one message to many targets.

import { getMessaging } from 'firebase-admin/messaging';
await getMessaging().send({ token, notification: { title: 'Hi', body: 'Test' } });

3Verify

Call it once from a script and check that it returns a message id string.

node send-test.js

Confirmed by firebase.google.com

Did this fix it?

Cause 3 of 3

The access token was minted without the messaging scope or from the wrong credentials

1Check

The token must be derived from a service account and carry the firebase.messaging scope. On Google infrastructure such as Cloud Functions, Application Default Credentials use the default service account; elsewhere GOOGLE_APPLICATION_CREDENTIALS must point at a service account key file.

echo $GOOGLE_APPLICATION_CREDENTIALS

2Fix

Point the variable at the service account JSON of the right project, or use the Admin SDK so the scope is set for you.

export GOOGLE_APPLICATION_CREDENTIALS=/path/to/service-account.json

3Verify

Initialise the Admin SDK and send a test message.

import { initializeApp } from 'firebase-admin/app';
initializeApp();

Confirmed by firebase.google.com

Did this fix it?

How do I stop it coming back?

  • Prefer the Admin SDK over hand-built HTTP calls so authorization is handled for you.
  • Keep the service account key out of the repository.
  • Grep for old send calls before upgrading firebase-admin.

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.