Stop at the first missing fact
Trace Web Push from left to right: environment, permission, service-worker registration, subscription, server request, push-service response, worker event, notification display, click handling, and operating-system settings.
Capture evidence at each boundary. Do not jump to the device when the server has not made a request.
Start with one known browser and one test endpoint
Remove audience queries, schedules, and bulk queues from the first investigation. Use one real device, one visible test action, one current subscription, and one short message. Record the browser environment, site origin, worker scope, internal endpoint-record ID, send-attempt ID, and time. This converts “notifications do not work” into a traceable transaction.
Step 1: verify environment and permission
console.table({
secure: window.isSecureContext,
serviceWorker: "serviceWorker" in navigator,
pushManager: "PushManager" in window,
notifications: "Notification" in window,
permission: "Notification" in window ? Notification.permission : "unavailable"
});
If a capability is missing, investigate the exact browser context, HTTPS, embedded-webview limitations, or platform prerequisites using the browser-support checklist. If permission is denied, site code cannot silently reverse it. On iPhone and iPad, confirm the site is being used as a Home Screen web app under the current platform behavior.
Step 2: inspect the service-worker registration
Use browser developer tools and navigator.serviceWorker.getRegistrations() to inspect script URLs, scopes, and active states. Confirm the intended worker is active for the page and another library has not replaced it. Fetch the worker URL directly: it should return JavaScript successfully, without an HTML error page or redirect. The service-worker implementation guide explains the scope and update rules behind this check.
If an updated worker is waiting, test both a fresh profile and an existing controlled tab. A registration success message does not prove that the version containing your push handler is active.
Step 3: compare the browser subscription with server storage
const registration = await navigator.serviceWorker.ready;
const subscription = await registration.pushManager.getSubscription();
console.log(subscription ? subscription.toJSON() : null);
If the value is null, no subscription exists for that registration. If it exists, compare a redacted endpoint fingerprint and key presence with the server record for the correct site. Upsert the current record before testing, following the subscription lifecycle and storage model. Check whether a VAPID key change created a subscription population the current private key cannot serve.
Step 4: inspect the exact server attempt
Confirm the send path selected the expected endpoint, VAPID key version, TTL, payload schema, and byte count. Capture the HTTP status and bounded response data from the push service. Classify the result with the Web Push delivery status-code guide: a 404 or 410 commonly means retirement, a 429 needs delayed pacing, and a 5xx may justify bounded retry.
If no request appears, the problem is in audience selection, scheduling, queueing, credentials, or worker execution before the push service. Do not debug the browser until the server has made an attempt.
Step 5: instrument the push event
Temporarily add safe diagnostic logging inside the service worker or use the browser’s worker debugger. Confirm the event fires, event.data exists when expected, JSON parsing succeeds, and the promise passed to event.waitUntil() settles. Validate the payload against the worker’s supported schema version.
A push-service success with no worker event can involve device connectivity, browser background restrictions, expired local state, or an outcome that service acceptance alone cannot reveal. Repeat with the browser running, backgrounded, and closed to narrow the condition.
Step 6: isolate notification display
Call registration.showNotification() from a controlled page action with granted permission. If that does not display, inspect operating-system notification settings, Focus or quiet modes, browser settings, and whether the options are valid. If it does display, the fault is earlier in push-event data or execution.
Step 7: verify click handling and destination
Confirm the notificationclick listener runs, closes the alert, and passes a safe URL to clients.openWindow() or an existing client. Inspect whether the destination redirects, requires authentication, or loses the campaign identifier. A displayed notification with a broken destination is not a successful user journey.
Use a symptom-to-boundary table
| Symptom | First boundary to inspect |
|---|---|
| Subscribe button does nothing | Capability checks, click handler, permission state, and console errors. |
| Permission granted but no endpoint | Worker readiness, public-key decoding, and subscribe() rejection. |
| Server gets 401 or 403 | VAPID key match, audience, token expiry, and server clock. |
| Server gets 404 or 410 | Subscription lifecycle; retire and allow a new browser subscription. |
| Push event fires but nothing appears | Payload parsing, waitUntil(), showNotification(), and permission. |
| Notification appears but tap fails | Click listener, safe destination, client focus, and page routing. |
Keep a reproducible diagnostic record
When the trace reaches the application layer, compare it with PushNotifications.org's delivery workflow so the diagnosis uses the product's actual permission, scheduling, response, and cleanup boundaries. Before releasing the correction, turn the reproduced failure into a case in the Web Push notification testing checklist.
Save the sequence, timestamps, non-secret IDs, status codes, browser and operating-system versions, and which state first diverged. Never paste complete subscription credentials or private keys into a ticket. The W3C Push API, MDN’s Service Worker API guide, and RFC 8030 provide the standards boundaries for this trace.