Repository navigation
Error Codes pwa
github-actions[bot] edited this page Nov 16, 2026
·
2 revisions
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 |
Ultimate — v31.43.0 As of 2026-10. The full-stack framework where the primary developer is an AI agent: bunx create-ultimate myapp → Getting started · live demo. MIT licensed. What npm serves is npm view @ultimat3/core version, never this line, and this footer is the only page that stamps a version.
Repository · Issues · Changelog · llms.txt
Edits to these pages are synced from wiki/ in the repository — change the file there, not the wiki, or the next sync overwrites it.
Start
- Getting started
- Installation
- Shapes
- Bare VM
- Project layout
- Migrating an existing app
- Compared to other stacks
Tutorials
- 1 · First app
- 2 · First feature
- 3 · Auth and admin
- 4 · Jobs and realtime
- 5 · Deploy free
- 6 · Growing up
Primitives
- The eight primitives
- Building your own base
- Actions
- Entities and migrations
- Policies and authz
- Queries and live queries
- Client data
- Jobs and workflows
- Scheduled tasks
- Routes and render modes
Capabilities
- Realtime
- Caching and invalidation
- Batching and preloading
- N+1 detection
- PWA and offline
- Client navigation
- MCP and AI
- Agents
- Admin dashboard
- Scraping
- Auth
- Notify
- Storage and uploads
- Feature flags
- SEO
- Static assets
Cross-cutting
- I18n
- Theming
- UI components
- Interface rules
- Timezones and dates
- Money
- Outbound HTTP
- Resource management
- Migrations and backfills
- Testing
- CI: the gate across parallel jobs
Reference