> This page is part of the [Customer.io documentation](https://docs.customer.io). For the complete index, see [llms.txt](https://docs.customer.io/llms.txt). > Last updated: October 23, 2026 > To take actions in Customer.io from an agent, use the [Customer.io CLI](https://docs.customer.io/ai/cli/get-started.md) or the [MCP server](https://docs.customer.io/ai/mcp/get-started.md). # Troubleshoot web push Find out why a web push notification didn't arrive, what each web push failure reason means, and how people can turn notifications back on after they block them. ## Check the delivery first A successful subscription, or a successful `identify` call, doesn’t mean that a notification arrived. When a notification doesn’t show up, start with its delivery in Customer.io: 1. Open the automation or broadcast and go to the **Sent** tab. You can also find the delivery in the person’s activity. 2. Find the delivery for your test person and check its status. Expand the row to see its failure reason, if it has one. What you see What it means No delivery at all The person doesn’t have a web device. They haven’t subscribed, they signed out (which removes the browser from their profile), or their browser unsubscribed. Check the **Devices** tab on their profile. **Sent**, but not **Delivered** Customer.io handed the notification to the browser’s push service, but the browser hasn’t shown it yet. The browser might be closed or offline. The push service holds the notification for one day by default, or until your broadcast’s send deadline, and delivers it if the browser comes back online before then. See [browser support](https://docs.customer.io/messaging/channels/web-push/overview/#browser-support). **Delivered**, but you didn’t see anything The service worker showed the notification, but the operating system might have hidden it. Check the computer’s or phone’s notification settings and Focus or **Do Not Disturb** settings. **Opened** Someone clicked the notification or one of its buttons. **Suppressed**, **Bounced**, or **Failed** Customer.io didn’t send the notification, or the push service refused it. Check the [failure reason](#failure-reasons). ## Failure reasons Failure reason What it means What to do `WEBPUSH_RENDER_FAILED` The **Notification icon**, **Badge**, **Action buttons**, **Replace earlier notification with the same tag**, **Show time (event time instead of arrival)**, or **App badge count (Safari / Home Screen apps)** use a Liquid variable that doesn’t exist for this person or event, so Customer.io didn’t send the notification. Customer.io retries the delivery in case the data arrives, and the delivery fails if it still doesn’t render. A missing variable in the title, message, or another field that app push also uses fails the delivery with a Liquid error instead. Add the missing data to your event or person, or use the `default` filter (latest Liquid) or an `if/else` fallback (legacy Liquid). See [personalize with Liquid](https://docs.customer.io/messaging/channels/web-push/send/#personalize-with-liquid). `WEBPUSH_UNREGISTERED` The browser isn’t subscribed anymore. The person turned off notifications, cleared their site data, or the subscription expired. Customer.io removes the device from the person’s profile. Nothing. The person needs to subscribe again to get web push. `WEBPUSH_CUSTOM_PAYLOAD_UNSUPPORTED` The message uses the **Custom Payload** editor. Customer.io only sends **Rich Push** messages to browsers. Rebuild the message with the **Rich Push** editor. `WEBPUSH_PAYLOAD_TOO_LARGE` The rendered notification is bigger than browsers allow. Shorten your text, URLs, or custom data. Remember that Liquid can make fields longer than they look in the composer. `WEBPUSH_INVALID_REQUEST` The push service refused the notification. Try sending again. If it keeps happening, contact support. `WEBPUSH_VAPID_AUTH_FAILED` The push service refused your workspace’s web push credentials. Customer.io retries the delivery. Check that **VAPID subject** in **Settings > Push > Web** uses a real, public domain you control. Apple rejects subjects like `mailto:alerts@example.test`. Fix the subject and click **Save**; don’t regenerate your keys. `WEBPUSH_VAPID_REJECTED` The browser subscribed with a different public key than your workspace uses now, usually because someone regenerated the keys. The person needs to subscribe again. Make sure your website uses the current public key from **Settings > Push > Web**. `WEBPUSH_INVALID_SUBSCRIPTION` or `WEBPUSH_MISSING_KEYS` The web device on the person’s profile is missing information that Customer.io needs to send to it. Make sure you add web devices with our web push plugin. The person needs to subscribe again. `WEBPUSH_RETRYABLE` The push service was busy or unavailable. Customer.io retries the delivery. Nothing. `NoProviderConfigured` Web push isn’t set up for this workspace. [Generate your web push keys](https://docs.customer.io/messaging/channels/web-push/set-up/#generate-keys). ## Notifications are blocked When someone blocks notifications for your site, the browser stops asking, and your website can’t change that. In Safari and Firefox, closing the permission prompt without choosing (for example, by pressing Escape) also blocks notifications, and your site can’t tell the difference. When `Notification.permission` is `denied`, show people how to allow notifications for your site in their browser, then ask them to click your button again. Browser How to allow notifications again Chrome and Edge Click the site controls icon to the left of the address, open the site’s settings or permissions, and set **Notifications** to **Allow**. Labels vary by version. Firefox Click the crossed-out bell or the permissions icon to the left of the address, and remove the **Send notifications: Blocked** permission. Then click your button again and choose **Allow**. You can also go to **Settings > Privacy & Security > Permissions > Notifications**. Safari on macOS Go to **Safari > Settings > Websites > Notifications** and set your site to **Allow**, or remove it so that Safari asks again. If notifications are allowed but don’t appear, check **System Settings > Notifications** and Focus. Safari on iOS and iPadOS Go to **Settings > Notifications**, choose your Home Screen app, and turn on **Allow Notifications**. Then open the app from the Home Screen. ## Other common problems ### The button doesn’t show a permission prompt * **Safari:** Make sure your click handler calls `webPush.subscribe()` before it waits for anything. See [ask for permission in a click](https://docs.customer.io/messaging/channels/web-push/set-up/#subscribe-in-a-click). * **iPhone and iPad:** Web push only works in a web app that the person added to their Home Screen and opened from there. See [iOS and iPadOS](https://docs.customer.io/messaging/channels/web-push/set-up/#ios-and-ipados). * **Any browser:** The browser doesn’t ask again after someone blocks notifications. See [notifications are blocked](#blocked). ### Subscribing fails because of a different service worker The plugin won’t replace a different service worker at the same path. Import our worker into your existing worker, or give our worker its own folder. See [if your site already has a service worker](https://docs.customer.io/messaging/channels/web-push/set-up/#existing-service-worker). ### Notifications arrive, but metrics don’t The service worker reports delivered and opened metrics to the `trackUrl` you set in the plugin. If you register the service worker yourself, keep the `?track=` query that the plugin adds to the worker’s URL. Also check that your `trackUrl` matches your account’s region. ### Clicking the notification opens the wrong page The notification only opens links that resolve to `https://` URLs. A relative **Link** resolves against your site’s origin, not the service worker’s folder. For example, `/bookings/123` opens `https://www.yourbrand.com/bookings/123` on that site. A button without a URL opens **Link**. A button URL must be a full `https://` address. If it isn’t, Customer.io removes that button and sends the rest of the notification. If **Link** is empty or doesn’t resolve to an `https://` URL, the notification opens your site’s home page. Use full `https://` addresses in **Link** and your button URLs to make the destination explicit for every person. ### Only one of a person’s browsers gets the notification Your message sends to the **Last used device**. See [last used device or all devices](https://docs.customer.io/messaging/channels/web-push/send/#device-audience). ### A person who signed out still gets notifications Call `cioanalytics.reset()` when people sign out. It removes the browser from their profile.