Maaz Zindani

Loading the index…

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

The iOS push arrives from FCM but plays no sound

ErrorThe notification banner appears on iOS but no sound plays

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

  • Applies to FCM HTTP v1, firebase-admin Node.js 13, Xcode 26, iOS 18
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 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));
  2. 2Match what you see, then jump to its fix

    1. 1The printed message has notification title and body but no apns.payload.aps.soundThe payload has no sound key under apnsFix
    2. 2A custom name such as alert.caf is set, and nothing playsThe sound file named in the payload is not inside the appFix
    3. 3The 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

What does the error look like?

  • The notification banner appears on iOS but no sound plays
  • A 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 sound

Confirmed by developer.apple.com

Did this fix it?

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 Resources

2Fix

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 device

Confirmed by developer.apple.com

Did this fix it?

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: true

Confirmed by developer.apple.com

Did this fix it?

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:

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

Next step

Want this handled for good?

I look after servers, apps and releases end to end. Tell me what keeps breaking.