Firebase Cloud Messaging troubleshooting & FAQ

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.

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 and Android.

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.

Why isn't onMessageReceived being called in my Android app?

When your app is in the background, notification messages 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.

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 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, <exclude domain="file" path="PersistedInstallation.W0R...GQ.json" />

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.

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.

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

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.

How long will it take for my quota increase request to be fulfilled?

Your quota increase request 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 updated to increase the chances of receiving service announcements.

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 and the device group feature 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.

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:

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.

How long will the legacy AndroidConfig (v1) API be supported?

FCM plans to continue supporting v1 AndroidConfig payloads for multiple years following the General Availability (GA) release of AndroidConfigV2. While the migration timeline spans multiple years, AndroidConfigV2 provides more predictable notification delivery, and you're encouraged to migrate as soon as possible.

What Android OS versions are supported by AndroidConfigV2?

AndroidConfigV2 will be supported on all Android versions that are supported by Google. All but 10+ year old devices will be supported when the legacy v1 API is decommissioned.

Will AndroidConfigV2 deliver payloads to devices that only support the older v1 interface, and in what order should I roll out changes?

Yes. When you send an AndroidConfigV2 request, FCM and GMS Core automatically translate the payload for devices running older client SDKs or for apps that haven't overridden onNotificationReceived() or onBackgroundSyncReceived() yet, delivering it using onMessageReceived().

Why does AndroidConfigV2 require returning notifications through the FCM SDK instead of calling NotificationManager.notify() directly?

By returning a NotificationResponse to the open-source FCM SDK, or using FcmNotificationManager:

• Your app receives a protected execution window to decrypt or customize the notification.
• If your app runs out of time, GMS Core ensures timely delivery by posting the backup notification you configured in remote_notification.notification.

Does AndroidConfigV2 handle notifications differently when my app is in the foreground versus the background?

No. Unlike legacy v1 notification messages, AndroidConfigV2 does not split message routing based on whether your app is in the foreground or background. When you send a RemoteNotification, the notification is displayed automatically in both states unless you set mutable_content: true and explicitly silence it in onNotificationReceived() using NotificationResponse.createEmpty().

How much time does my app get when handling a mutable RemoteNotification?

When mutable_content: true is set on a RemoteNotification, your app has up to 20 seconds inside onNotificationReceived() to decrypt payloads, fetch small assets (such as avatars), or contact your app server before returning a NotificationResponse. If the callback exceeds 20 seconds, execution is cancelled and GMS Core automatically posts a fallback notification based on the remote_notification.notification payload.

How does notification suppression enforcement work for mutable RemoteNotifications?

Apps can suppress a RemoteNotification by returning NotificationResponse.suppress() from onNotificationReceived(). For example, when a chat is muted, a sender is blocked, or an end-to-end encrypted payload fails validation.

• In the background: Your app can suppress up to 25% of received RemoteNotification messages over a rolling window. If your app's background suppression rate exceeds 25%, GMS Core automatically renders and posts the fallback notification from the remote_notification.notification payload.
• In the foreground: You're free to suppress all Remote Notifications while active in the foreground. For example, to display an in-app toast or update an open chat screen instead of posting a system notification.

Can my app post multiple notifications or cancel an existing notification from a single RemoteNotification?

Yes. Use the following to cancel or post multiple notifications:

• Cancel a single notification: Return NotificationResponse.createCancel(tag, id) from onNotificationReceived() to dismiss a previously posted notification.
• Post multiple notifications or combine cancels and posts: Call getFcmNotificationManager(message) inside onNotificationReceived() to invoke postNow(tag, id, notification) and cancelNow(tag, id) multiple times, and return manager.finished() when complete.

Can custom RemoteViews work with AndroidConfigV2?

Yes, custom RemoteViews will work with AndroidConfigV2. onNotificationReceived() returns a standard Android Notification object, all standard Android notification APIs, such as setCustomContentView(), remain supported. Note that RemoteViews and Views are in maintenance mode, and it's recommended to migrate to Compose.