This page provides troubleshooting help and answers to frequently asked
questions about Cloud Messaging.
### What's the
difference between the the Notifications composer and FCM?
Firebase Cloud Messaging provides a complete set of messaging
capabilities through its client SDKs and HTTP server
protocol. For deployments with more complex messaging requirements,
FCM is the right choice.
The Notifications composer is a lightweight, serverless messaging
solution built on Firebase Cloud Messaging. With a user-friendly
graphical console and reduced coding requirements,
the Notifications composer lets users send messages to
re-engage and retain users, foster app growth, and support marketing
campaigns.
| **Capabilities** | | **Notifications composer** | **Cloud Messaging** |
|---|---|---|---|
| **Target** | Single device | Yes | Yes |
| | Clients subscribed to topics (i. e. weather) | Yes | Yes |
| | Clients in predefined user segment (app, version, language) | Yes | No |
| | Clients in specified analytics audiences | Yes | No |
| | Clients in device groups | No | Yes |
| | Upstream from client to server | No | Yes |
| **Message Type** | Notifications up to 2kb | Yes | Yes |
| | Data messages up to 4kb | No | Yes |
| **Delivery** | Immediate | Yes | Yes |
| | Future client device local time | Yes | No |
| **Analytics** | Built-in Notifications analytics collection and funnel analytics | Yes | No |
### Do I need to use other
Firebase services in order to use FCM?
You can use Firebase Cloud Messaging as a standalone component, without using
other Firebase services.
### Why do my targeted devices
apparently fail to receive messages?
When it looks like devices haven't successfully received messages, check first
for these two potential causes:
**Foreground message handling for notification messages.** Client apps need to
add message handling logic to handle notification messages when the app is in
the foreground on the device. See the details for
[iOS](https://firebase.google.com/docs/cloud-messaging/ios/receive-messages) and
[Android](https://firebase.google.com/docs/cloud-messaging/android/receive-messages#override-onmessagereceived).
**Network firewall restrictions.** If your organization has a firewall that
restricts the traffic to or from the Internet, you need to configure it to allow
connectivity with FCM in order for your Firebase Cloud Messaging client
apps to receive messages. The ports to open are:
- 5228
- 5229
- 5230
FCM usually uses 5228, but it sometimes uses 5229 and 5230.
FCM doesn't provide specific IPs, so you should allow your firewall to
accept outgoing connections to all IP addresses contained in the IP blocks
listed in Google's [ASN of 15169](https://bgp.he.net/AS15169#_prefixes).
### Why
isn't `onMessageReceived` being called in my Android app?
When your app is in the background, [notification
messages](https://firebase.google.com/docs/cloud-messaging/customize-messages/set-message-type)
are displayed in the system tray, and `onMessageReceived` is not called. For
notification messages with a data payload, the notification message is displayed
in the system tray, and the data that was included with the notification message
can be retrieved from the intent launched when the user taps on the
notification.
For more information, see [Receive and handle
messages](https://firebase.google.com/docs/cloud-messaging/android/receive-messages#override-onmessagereceived).
### Why do I get 404
error when I send messages to an active app instance restored from a backup?
FID (Firebase Installation ID) is the identifier of an app instance. By default,
Firebase Installation data is backed up and restored. So in the restoration
case, the restored app instance and the original app instance share the same
FID. Since FCM only stores one token per FID, if both the original app instance
and the restored app instance are in use, then when one app instance registers
with FCM, the other app instance's token is removed, which causes 404
errors.
We recommend developers to do the following in their app:
- [Exclude](https://developer.android.com/identity/data/autobackup#xml-include-exclude) Firebase installation data in backup. The Firebase installation data is stored in a `PersistedInstallation....json` file. The filename is a constant for an app. For example, ``
### Apple
announced they're deprecating the legacy binary protocol for APNs. Do I need to
do anything?
No. Firebase Cloud Messaging switched to the HTTP/2-based APNs protocol in 2017.
If you're using FCM to send notifications to iOS devices, there should
be no action required on your part.
## FCM quotas and limits
### How do I notify a large customer
base within 2 minutes?
This use case cannot be supported. You must spread your traffic out over 5
minutes.
### My app notifies users of
events, and these messages must be delivered immediately to support my business
model. Can I get more quota?
Unfortunately, we cannot grant quota increases for this reason. You must spread
your traffic out over 5 minutes to [avoid spiky
traffic](https://firebase.google.com/docs/cloud-messaging/scale-fcm#avoid-spikes).
### My messages are about
scheduled events. How can I send all traffic at the top of the hour?
We recommend that you start sending the notifications at least 5 minutes prior
to the event. Alternatively, send [data
messages](https://firebase.google.com/docs/cloud-messaging/customize-messages/set-message-type#data-messages)
and implement your platform's analog of `onMessageReceived` handler to schedule
local notifications ahead of time.
### How can I monitor my quota usage?
See Google Cloud guidance on how to [chart and monitor quota metrics](https://cloud.google.com/monitoring/alerts/using-quota-metrics).
### 429 errors are hard
for me and my business to handle. Can I get an exemption or more quota to avoid
getting 429s?
While we understand that quota limits can be challenging, quotas are vital to
keeping the service reliable and we can't grant exemptions. Use retries to
properly [handle 429 errors](https://firebase.google.com/docs/cloud-messaging/scale-fcm#handling-retries).
### How long will it
take for my quota increase request to be fulfilled?
Your [quota increase
request](https://firebase.google.com/docs/functions/quotas#when_you_reach_a_quota_limit) depends on your
use of FCM. In any case, you can expect an answer in a few business
days. In some cases, there may be some back-and-forth regarding your usage of
FCM and various circumstances, which can prolong the process. If all
requirements are met, most requests will be handled within 2 weeks.
### Can I get more quota for a
temporary event?
You can request additional quota to support an event lasting up to 1 month.
File the request at least 1 month in advance of the event and with clear details
on when the event starts and ends, and FCM will make every practical
effort to fulfill the request. If granted, these quota increases will be
reverted after the event's end date.
### Is my current quota subject
to change?
While Google won't do so lightly, quotas may be changed as needed to protect the
integrity of the system. When possible, Google will notify you in advance of
such changes. Keep your [Cloud MSA
contacts](https://cloud.google.com/docs/cloud-msa) updated to increase the
chances of receiving service announcements.
## FCM legacy API deprecations
### Server side APIs deprecated in September 2026
### Which APIs and features are deprecated and will be decommissioned? What should I do if I'm using these APIs?
All the [InstanceId server APIs](https://developers.google.com/instance-id/reference/server)
and [the device group feature](https://firebase.google.com/docs/cloud-messaging/device-group) are
deprecated and will be decommissioned on September 29, 2027. The following table
shows more details about the deprecated APIs/features and the action required.
| API Name | API Endpoint | Intended Use | Customer Impact | Action Required |
|---|---|---|---|---|
| InstanceId info API | https://iid.googleapis.com/iid/info | Getting info related to an InstanceId / FCM token | Requests to this API will start failing after September 29, 2027. | For customers using the API for token validation, use [FCM V1 send API](https://firebase.google.com/docs/reference/fcm/rest/v1/projects.messages/send) and set `validate_only` to true. For customers using the API for getting topic subscription info, migrate to the [new topic subscription API](https://firebase.google.com/docs/reference/fcm/fcmtopics/rest). |
| InstanceId topic subscription API | https://iid.googleapis.com/iid/v1/.../rel/topics https://iid.googleapis.com/iid/v1:batchAdd https://iid.googleapis.com/iid/v1:batchRemove | Subscribing token(s) to a topic via the legacy topic subscription API. | Requests to these API will start failing after September 29, 2027. | Migrate to the [new FCM topic subscription server API](https://firebase.google.com/docs/reference/fcm/fcmtopics/rest) for [topic subscription and unsubscription](https://firebase.google.com/docs/cloud-messaging/manage-topic-subscriptions#manage-topic-subscriptions-server-side-api). |
| InstanceId batch import API | https://iid.googleapis.com/iid/v1:batchImport | Creating FCM tokens for iOS in a batch on the server side. | Requests to this API will start failing after September 29, 2027. Creating FCM registrations from APNs tokens on the server side won't be supported. | You can use [Apple's APNs service](https://developer.apple.com/documentation/usernotifications/sending-notification-requests-to-apns) to send notifications using APNs tokens. To get extra benefits provided by FCM, integrate your app with [FCM iOS SDK](https://firebase.google.com/docs/cloud-messaging/ios/get-started), which will create FCM registrations on the client. |
| Device group management API | https://fcm.googleapis.com/fcm/notification https://fcm.googleapis.com/gcm/notification https://fcm.googleapis.com/iid/notification https://fcm.googleapis.com/notification | Adding / removing/ retrieving device group members. | Requests to this API will start failing after September 29, 2027. | See [the guidance](https://firebase.google.com/docs/cloud-messaging/migrate-off-device-groups) for migrating off the feature. Messages can still be sent to individual FCM registrations instead of group tokens. |
| Device group send | https://fcm.googleapis.com/v1/projects/.../messages:send | Sending messages to device groups using group notification_key. | This API will continue working but it won't support device group tokens after September 29, 2027. | See [the guidance](https://firebase.google.com/docs/cloud-messaging/migrate-off-device-groups) for migrating off the feature. Messages can still be sent to individual FCM registrations instead of group tokens. |
### If I'm using Firebase Admin SDK to manage topic subscriptions, will I be impacted by the deprecation? What should I do?
If you are using earlier versions of Firebase Admin SDK to manage topic subscriptions, you will be impacted by the deprecation.
You will need to upgrade your Firebase Admin SDK to the
following versions:
| Platform | Admin SDK version being impacted | Admin SDK version to be upgraded to |
|---|---|---|
| Node.js | \<=14.4.0 | \>=14.5.0 |
| Python | \<=7.6.0 | \>=7.7.0 |
| Java | \<=9.10.0 | \>=9.11.0 |
| Go | \<=4.21.0 | \>=4.22.0 |
| .NET | \<=3.6.0 | \>=3.7.0 |
### Will I see a service downgrade before September 29, 2027?
No. You have 12 months to migrate from the deprecated APIs to alternatives without any service downgrade. We strongly recommend you to plan the migration as early as possible so you won't be impacted by the decommissioning.
You are expected to receive errors when calling deprecated APIs after September 29, 2027.
### Can new users onboard the deprecated APIs/features before the decommission?
New users can onboard the deprecated APIs/features before January 1st, 2027.
After January 1st, 2027, new users won't be able to use the deprecated APIs.
Users who are using the deprecated APIs can continue using them until September
29, 2027.