Mastodon push notifications on your iPhone or iPad have stopped arriving. You open the app and see replies, boosts, and new followers, but your lock screen stays silent. This problem usually happens because the iOS notification permission expired, the Mastodon server changed its push endpoint, or a recent iOS update reset notification settings. This article explains the three most common causes and walks you through the exact steps to restore push notifications on iOS.
Each fix targets a specific failure point. You will re-enable system-level permissions, verify the Mastodon app’s notification settings, and check whether your instance supports push notifications at all. No third-party tools or jailbreak is required.
Key Takeaways: Restoring Mastodon Push Notifications on iOS
- Settings > Notifications > Mastodon > Allow Notifications: Re-enables the system-level permission that iOS may have revoked after an update.
- Mastodon App > Preferences > Push Notifications: Confirms that the app itself is set to send alerts for replies, boosts, and follows.
- Server-side check via web browser: Verifies that your Mastodon instance supports the Web Push API and that your device token is registered.
Why Mastodon Push Notifications Stop Working on iOS
Mastodon uses the W3C Push API to deliver notifications. On iOS, the Mastodon app registers a device token with the instance server. When something new happens—a reply, a boost, a follow—the server sends a push message to Apple Push Notification service, which forwards it to your device.
Three things break this chain most often.
First, iOS can revoke notification permissions for an app after a major update or if the user accidentally tapped Don’t Allow during a reinstall. The Mastodon app still thinks it can send notifications, but iOS blocks them at the system level.
Second, the Mastodon app’s own notification settings may have changed. A profile switch, an account logout, or a settings reset inside the app can disable push notifications for specific event types.
Third, the instance server may have lost the device token. This happens when the instance administrator restarts the push relay service, changes the push endpoint URL, or when the token expires. iOS push tokens can change after an OS update or a backup restore.
Step-by-Step Fix to Restore Mastodon Push Notifications on iOS
Perform these steps in order. Test after each step by asking someone to reply to a post or by boosting one of your own posts from another account.
- Check iOS System Notification Permission
Open Settings on your iPhone or iPad. Scroll down and tap Mastodon. Tap Notifications. Ensure the toggle for Allow Notifications is green. Below that, verify that Lock Screen, Notification Center, and Banners are all enabled. Set Sounds to on if you want an audible alert. If the toggle was off, turn it on and test. - Enable Push Notifications Inside the Mastodon App
Open the Mastodon app. Tap the profile icon in the bottom-right corner. Tap the gear icon to open Settings. Tap Notifications. Under Push Notifications, make sure the toggle is on. Below that, enable each event type you want to receive: Favourite, Follow, Reblog, Mention, Poll, and Follow Request. If any were off, turn them on and test. - Re-register the Device Token with Your Instance
Still in the Mastodon app Settings, scroll to the bottom and tap Clear Push Subscription. This removes the old token from the server. Close the app completely by swiping it away from the App Switcher. Reopen the app. The app will automatically request a new token from Apple and send it to your instance. Test notifications again. - Verify Server-Side Push Support
Open Safari and go to your Mastodon instance’s web interface. Log in. Click Preferences in the left column. Click Notifications. Scroll to Push Notifications. If you see a green checkmark next to “Push notifications are enabled,” the server supports them. If you see a red X, your instance does not have the push relay service running. Contact your instance administrator and ask them to enable the mastodon-pushrelay service. - Reset All Mastodon App Settings as a Last Resort
If none of the above worked, go to Settings > General > Transfer or Reset > Reset. Tap Reset All Settings. This clears all app data including cached tokens and preferences. You will need to log in again. After logging in, repeat steps 1 through 3. This forces a completely fresh push registration.
If Mastodon Still Has Issues After the Main Fix
Notifications arrive only when the app is open
This means the app is using local polling instead of push. Go back to step 3 and perform the Clear Push Subscription action. Then force-close the app and reopen it. If the problem persists, your instance may not support push at all. Check the server-side step 4.
Notifications work on one account but not another
Mastodon stores push tokens per account. If you added a second account in the app, that account may not have push enabled. Tap your profile icon, tap the account switcher at the top, select the other account, and repeat step 2 for that account.
Notifications stopped after an iOS update
iOS 17 and later sometimes reset notification permissions for third-party apps after a major version upgrade. Go to Settings > Notifications > Mastodon and confirm the toggle is on. If it is off, turn it on. The app will automatically re-register its token the next time you open it.
Server returns “Push subscription not found” error
This means the device token was deleted from the server side. Use step 3 to clear the local subscription and force a new registration. If the error continues, ask your instance admin to restart the push relay service with the command systemctl restart mastodon-pushrelay on the server.
Mastodon Push Notification Settings: iOS vs Web Interface
| Item | iOS Mastodon App | Web Interface (Safari) |
|---|---|---|
| Permission type | System-level toggle in Settings | Browser push permission prompt |
| Event-level control | Settings > Notifications > Push Notifications | Preferences > Notifications > checkboxes |
| Token registration | Automatic on first launch | Automatic when you click “Enable Push” |
| Clear subscription | Settings > Clear Push Subscription | Preferences > Notifications > Disable Push |
| Server requirement | Instance must run pushrelay service | Same requirement |
Push notifications on iOS depend on both the app’s internal settings and the server-side relay. The iOS app gives you direct control over token management, while the web interface offers a quick way to verify server support. Use the web interface as a diagnostic tool when the app behaves unexpectedly.
Conclusion
You can now restore Mastodon push notifications on iOS by checking the system permission, enabling push inside the app, and clearing the push subscription to force a fresh token registration. Test notifications after each step to isolate the exact failure point. If the problem persists, verify that your instance runs the pushrelay service by checking the web interface under Preferences > Notifications. For advanced troubleshooting, ask your instance administrator to restart the mastodon-pushrelay service or to update the push endpoint URL in the server configuration file.