Mastodon Error ‘Push Notification Failed’ on Web Push Setup: Fix

When you try to enable web push notifications in Mastodon, you may see the error Push Notification Failed. This stops the browser from sending real-time alerts for replies, boosts, and follows. The error usually happens because the browser cannot register a service worker or the push subscription endpoint is blocked. This article explains the three main reasons for the failure and gives step-by-step fixes for each cause.

Why the Push Notification Failed Error Occurs

Mastodon uses the Web Push API to send notifications from its server to your browser. The process requires three things to work together: a registered service worker in the browser, a valid push subscription object, and a reachable push endpoint URL. If any of these steps fails, the browser shows Push Notification Failed.

The most common root causes are:

• Service worker not registered: The browser cannot find or start the JavaScript file that handles push events.
• Notifications blocked in browser permissions: The site is denied the Notification permission.
• Push endpoint unreachable: A firewall, proxy, or browser extension blocks the connection to the push server.

Less common causes include an expired push subscription or a browser that does not support the Web Push API at all. This guide covers all scenarios.

Steps to Fix Push Notification Failed in Mastodon

1. Check and enable browser notification permissions for Mastodon
   Open your browser settings and go to Site Permissions or Privacy and Security. Find the Mastodon instance URL and set the Notification permission to Allow. If you are using Chrome, go to Settings > Privacy and Security > Site Settings > Notifications and add your Mastodon instance to the Allow list.
2. Re-register the push subscription from Mastodon preferences
   Log in to your Mastodon account. Go to Preferences > Notifications. Scroll to Web Push Notifications. If the toggle is on, turn it off. Wait 10 seconds, then turn it back on. This sends a new push subscription request to the browser.
3. Verify the service worker is registered
   Open your browser Developer Tools (F12). Go to the Application tab. In Chrome, select Service Workers from the left menu. You should see a service worker registered for your Mastodon instance with the status Running. If the status is Error or Stopped, click Unregister, then reload the Mastodon page and repeat step 2.
4. Clear the push subscription and service worker cache
   In the same Developer Tools panel, go to Storage or Cache Storage. Delete all entries related to your Mastodon instance. Then go to the Service Workers panel and click Unregister. Reload the Mastodon page and enable web push notifications again from Preferences.
5. Disable browser extensions that block push APIs
   Extensions like uBlock Origin, Privacy Badger, or NoScript can block the service worker registration or the push endpoint. Temporarily disable all extensions, then reload Mastodon and try enabling push notifications again. If the error goes away, re-enable extensions one by one to find the culprit.
6. Check for corporate firewall or VPN interference
   Some corporate networks or VPNs block WebSocket connections or push endpoints. Try accessing Mastodon from a different network, such as a mobile hotspot. If the error disappears, the network is blocking push. Contact your IT department or switch to a different VPN provider that allows WebSocket traffic.
7. Update your browser to a version that supports Web Push
   Mastodon web push requires a browser that supports the Push API and Service Workers. Supported browsers include Chrome 50+, Firefox 44+, Edge 17+, and Safari 16+. Opera and Brave also work. If you use an outdated browser, update it to the latest version.

If Mastodon Still Shows Push Notification Failed After the Main Fix

Push subscription expired and cannot renew

Each push subscription has a lifetime. Some browsers expire subscriptions after 24 hours. If you do not visit Mastodon for a long time, the subscription becomes invalid. To fix this, log in to Mastodon, go to Preferences > Notifications, turn off Web Push Notifications, save, then turn it back on. This creates a fresh subscription.

Mastodon instance server blocks push endpoints

Some Mastodon instances disable push notifications for performance or privacy reasons. Instance administrators can set the environment variable PUSH_ENDPOINT to a custom endpoint or leave it empty to disable push entirely. If you cannot enable push on one instance, try logging in to a different instance that supports push. You can check your instance status by asking the admin or looking at the instance about page.

Browser uses strict privacy settings that block service workers

Browsers like Brave with Shields Up or Firefox with Enhanced Tracking Protection set to Strict can block service workers. For Brave, click the lion icon in the address bar and set Shields to Down for the Mastodon instance. For Firefox, click the shield icon and turn off Enhanced Tracking Protection for the site. Then reload Mastodon and repeat the push setup.

Mastodon Push Notification Methods: Browser vs Mobile App

Item	Browser Web Push	Mobile App Push
Delivery method	Service Worker + Push API	Platform push service (APNs, FCM)
Requires browser open	No, but browser must be running	No, works when app is closed
Common failure cause	Blocked service worker or permissions	Invalid device token or app permissions
Configuration location	Preferences > Notifications	App Settings > Notifications
Supported browsers or OS	Chrome, Firefox, Edge, Safari 16+	iOS 14+, Android 6+

If browser push continues to fail, consider using the official Mastodon mobile app for reliable push notifications. The app uses the platform-specific push service and does not depend on browser service workers.