The iOS push arrives from FCM but plays no sound
The notification banner appears on iOS but no sound playsShort answer
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. Add sound set to default to the APNs payload you send, make sure a custom sound file really ships inside the app, and check that the app asked for the sound permission.
Fix it fast
1Find out which cause you have
Print the exact JSON you send to FCM and look for aps.sound under the apns block. If it is missing, that is the cause.
console.log(JSON.stringify(message, null, 2));2Match what you see, then jump to its fix
- 1
The printed message has notification title and body but no apns.payload.aps.soundThe payload has no sound key under apnsFix - 2
A custom name such as alert.caf is set, and nothing playsThe sound file named in the payload is not inside the appFix - 3
The payload is right but the device plays no sound for this app onlyThe app never asked for sound permission, or the user turned sounds offFix
- 1
What does the error look like?
The notification banner appears on iOS but no sound playsA custom sound name in the payload is ignored and nothing plays
Cause 1 of 3
The payload has no sound key under apns
1Check
Apple's payload reference lists sound as a key of the aps dictionary, and FCM's apns.payload is where the aps dictionary goes. The Admin SDK's Aps type has a sound field.
console.log(message.apns?.payload?.aps?.sound);2Fix
Add the sound key. The string default plays the system sound.
const message = {
token,
notification: { title: 'Hi', body: 'Test' },
apns: { payload: { aps: { sound: 'default' } } },
};
await getMessaging().send(message);3Verify
Send it to a device with the app in the background and sound allowed.
# the banner arrives with the system alert soundConfirmed by developer.apple.com
Cause 2 of 3
The sound file named in the payload is not inside the app
1Check
Apple says the named file must already be on the device, in the app's main bundle or in the Library/Sounds folder of the app's container. Check the target's Copy Bundle Resources list for the file.
# Xcode: target > Build Phases > Copy Bundle Resources2Fix
Add the sound file to the app target so it ships in the bundle, keep the name in the payload identical to the file name, or use default.
apns: { payload: { aps: { sound: 'alert.caf' } } }3Verify
Install the new build, then send again; the custom sound plays.
# listen for the custom sound on a real deviceConfirmed by developer.apple.com
Cause 3 of 3
The app never asked for sound permission, or the user turned sounds off
1Check
Authorization is requested per interaction type. Apple notes that the system prompts only once and that people can change the allowed interaction types at any time.
UNUserNotificationCenter.current().getNotificationSettings { s in
print("sound setting enabled:", s.soundSetting == .enabled)
}2Fix
Include sound in the options you request, and if the user turned it off, ask them to enable Sounds under the app's notification settings.
try await UNUserNotificationCenter.current()
.requestAuthorization(options: [.alert, .sound, .badge])3Verify
The check prints true after sounds are enabled, and the next push plays a sound.
# Xcode console: sound setting enabled: trueConfirmed by developer.apple.com
How do I stop it coming back?
- Build push messages in one server function so the apns block is written once.
- Keep custom sound file names in a constants file shared by the server and the app release notes.
- Re-read the permission status at launch rather than assuming the first answer still holds.
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:
- WorkforceA field app, an admin console and a self-hosted Node.js server for push and reconciliation.
- TaxiDexMy own multi-tenant taxi dispatch SaaS: API, dispatcher portal, driver and passenger apps, and the servers underneath.
- SessionBirdAn omnichannel engagement suite in Flutter: campaigns, chatbot, tickets, analytics and live calling.
Related fixes
Mobile apps
A test push from the Firebase console never shows up on the iPhone
didReceiveRegistrationToken prints a token, yet no notification arrives
When a console message is accepted but the iPhone stays silent, the break is between Firebase and APNs or inside the app.
4 causes, each with a fixMobile apps
FCM rejects the message with INVALID_ARGUMENT
HTTP 400 from fcm.googleapis.com/v1/projects/PROJECT_ID/messages:send
INVALID_ARGUMENT is HTTP 400: FCM did not accept the request parameters.
3 causes, each with a fixMobile apps
Push sending broke because the server still uses the legacy FCM API
Console notice that the legacy Firebase Cloud Messaging API is deprecated
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.
3 causes, each with a fixMobile apps
FCM cannot reach an iPhone: APNs or web push credentials rejected
HTTP 401 when sending to an iOS registration token
THIRD_PARTY_AUTH_ERROR is HTTP 401.
2 causes, each with a fixMobile 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 fixMobile apps
Firebase on iOS asks for the FCM token before APNs has given one
Be sure to re-retrieve the FCM token once the APNS device token is set.
The Firebase Messaging SDK needs the APNs device token from iOS before it hands out an FCM token.
3 causes, each with a fix