Skip to content

Error Codes pwa

github-actions[bot] edited this page Nov 16, 2026 · 2 revisions

Error codes: @ultimat3/pwa

Part of Error codes: every code @ultimat3/pwa registers. x errors explain <CODE> --json prints the same row.

Code Means Typical cause Fix
X_BUILD_ID_MISSING no immutable build ID a build produced outside x build build with x build; never use a timestamp or latest
X_PWA_ICON_MISSING no source icon to generate from the configured icon path does not exist planIcons({ sourceIcon: 'apps/web/site/icon.png' }) — a square PNG, 1024x1024 or larger; under x build that file is the source
X_PWA_MANIFEST_INVALID the generated web manifest failed validation a bad start_url or scope fix the pwa block; cause names the field
X_PWA_NO_OFFLINE_FALLBACK pwa.offline.fallback is not set, or no route serves it the required field was removed, or the path it names has no page x g route offline --surface site, then set pwa: { offline: { fallback: '/offline' } }
X_PWA_PUSH_FAILED the push service did not accept the message, and may later a 429, a 5xx or a connection that never opened. retry-after: thrown by pushToActor after every other device was tried, so the notifier job retries x jobs list --json — the job retries on its policy. A stated Retry-After rides in meta.retryAfterSeconds, which a job calling pushToActor directly waits out; through pushChannel the failure is X_NOTIFY_DELIVERY_FAILED and the notifier's own backoff applies
X_PWA_PUSH_HOST_UNLISTED the push endpoint is not on a push service this app sends to a subscription's endpoint host is neither one of the built-in push services (PUSH_SERVICE_HOSTS in @ultimat3/pwa: FCM, Mozilla, Apple and WNS, and their subdomains) nor listed in pwa.vapid.pushHosts; an endpoint comes from a request body, so only a listed push service is ever dialled vapid: { subject: 'mailto:ops@example.com', pushHosts: ['push.example.com'] } — pwa.vapid.pushHosts in app.config.ts, for a push service the built-in list does not name
X_PWA_PUSH_PAYLOAD_TOO_LARGE the push message does not fit one 4096-byte record the rendered notification (title, body, actions, url) serialises past the 3993 bytes RFC 8291 leaves for plaintext in one record url: '/posts/1' — send a path to the content and shorten the catalog strings, never the content itself
X_PWA_PUSH_REJECTED the push service refused the message and will refuse it again a 400, 401, 403 or 413: a VAPID key the subscription was not made with, a subject the service refuses, or a body it will not take. Logged by pushToActor and counted as refused, never retried; on a 401 or 403 the subscription is deleted — it was made with a key this server no longer signs with — and subscribeToPush replaces a browser's stale one the next time it asks x vapid show — a 403 after a key change means every subscriber subscribes again
X_PWA_PUSH_SUBSCRIPTION_INVALID the push subscription is not one a browser produced endpoint is not https: to a public host (localhost and an IP literal that is loopback, private, link-local or otherwise not public are refused: the endpoint is where a caller points this server), p256dh is not a 65-byte uncompressed P-256 point, or auth is not 16 bytes. Refused by pushSubscribe() before storing; a stored one is deleted by the sender import { subscribeToPush } from '@ultimat3/pwa/client' — it sends PushSubscription.toJSON() unchanged
X_PWA_PUSH_UNCONFIGURED push is not configured in this process pushSubscribe(), pushUnsubscribe() or webPush() ran in a process whose boot installed no Web Push runtime: pwa.push is false, or pwa.enabled is pwa: { enabled: true, push: true, vapid: { subject: 'mailto:ops@example.com' } } in app.config.ts; a test calls installWebPush({ store, keys, subject }) first
X_PWA_STRATEGY_EXHAUSTED a caching strategy had no cache, no network and no fallback staleWhileRevalidate with no StrategyOptions.fallback and the network failed staleWhileRevalidate(request, env, { ...options, fallback }) — or pwa: { offline: { fallback: '/offline' } } in app.config.ts
X_PWA_SYNC_FLUSH_FAILED the background-sync outbox flush was rejected registered, thrown by nothing since 21.0.0. Until then the worker POSTed /_x/outbox/flush, a route nothing mounted, and raised this on a non-2xx. The worker now posts OUTBOX_DRAIN_MESSAGE to open tabs, and realtime's outbox replays over HTTP delete any branch that matches this code, because it never runs. An app still generating the old worker: delete backgroundSync: { flushEndpoint } from its generateServiceWorker call
X_PWA_SYNC_INCOMPLETE the background-sync outbox flush left mutations queued registered, thrown by nothing since 21.0.0, for the same reason as X_PWA_SYNC_FLUSH_FAILED: there is no flush endpoint to report remaining > 0. A queue left undrained stays in the page's IndexedDB and replays on the next load delete any branch that matches this code, because it never runs. pwa.backgroundSync is a boolean, and the retry schedule is the browser Background Sync API's own
X_PWA_VAPID_KEY_INVALID the VAPID key pair is malformed or not a pair ULTIMATE_VAPID_PUBLIC_KEY is not a 65-byte uncompressed P-256 point, ULTIMATE_VAPID_PRIVATE_KEY is not a 32-byte scalar, or the private key does not sign for the public one (the boot signs a probe and verifies it) x vapid create — one command writes both halves, so they cannot disagree
X_PWA_VAPID_KEY_MISSING no VAPID key pair for push pwa.push is true and ULTIMATE_VAPID_PUBLIC_KEY / ULTIMATE_VAPID_PRIVATE_KEY are unset (or hold the published development pair) in a deployed environment — or one half is set without the other, anywhere. Refused at boot, before any service starts x vapid create — seals a fresh pair into secrets.enc.json; or set both variables in the deployment's environment
X_SW_SCOPE_INVALID the service-worker scope cannot serve the routes it precaches a scope narrower than the app serve sw.js from the app root

Clone this wiki locally