Repository navigation
Error Codes notify
Part of Error codes: every code @ultimat3/notify registers. x errors explain <CODE> --json prints the same row.
| Code | Means | Typical cause | Fix |
|---|---|---|---|
X_NOTIFY_CHANNELS_EMPTY |
the notifier declares no channels | an empty deliver: []. Refused where it is written: a notifier with no channel resolves its recipients on every run and delivers to nobody |
deliver: [{ channel: inAppChannel() }] on notifier("<name>") — at least one entry; inAppChannel() is the one with no external driver |
X_NOTIFY_CHANNEL_DUPLICATE |
two deliveries share one channel name | two deliver entries naming the same channel. Refused because the delivery ledger's unique index is (notifier, key, channel, coalesce(recipient, '')): the second delivery would claim a row the first already owns and be dropped as a duplicate, so one of the two would silently never send |
deliveryChannel('<name>-digest', …) — the second channel's own name on notifier("<name>") — or merge the two deliver entries |
X_NOTIFY_DELIVERY_FAILED |
a channel did not accept the delivery | a channel's deliver threw. Wrapped rather than rethrown so the dead-letter row carries a stable code and names the channel — a raw provider error names only itself. The ledger row is settled failed first and stays re-claimable, so the job's own retry policy decides whether it goes out again. Rendered through renderThrowable, never ${cause}: a provider rejection is routinely an object whose toString throws |
x jobs list --json for the run, then x jobs show <id> --json — the failing step is deliver:<channel>, and meta.channel names it |
X_NOTIFY_DELIVERY_HELD |
another attempt holds this delivery | a live attempt holds the delivery claim, so this one neither sent nor treated the notification as gone out; the job retries once the claim is past its reclaim window |
x jobs list --json — the run retries on its own once the claim can be reclaimed; to shorten that, set reclaimAfterMs on postgresDeliveryLedger() |
X_NOTIFY_DIGEST_UNSUPPORTED |
a digest window is declared on a bulk channel |
digest: beside a bulkChannel(). Refused where it is written: a bulk send has one payload for the whole audience and a window coalesces PER RECIPIENT, so the two have no shared meaning — and inventing one would be this package deciding whose events get grouped |
{ channel, wait: '1h' } — that entry with digest dropped — or deliver it through deliveryChannel('<name>', …) one recipient at a time |
X_NOTIFY_FANOUT_TOO_WIDE |
the audience is larger than one run may fan out to | the resolved audience passed maxRecipients (default 500). One step per recipient is what makes a provider blip re-send one address rather than all of them, and a step is a durable row — so there is a width past which this is the wrong shape entirely. Refused with both numbers rather than degraded silently |
bulkChannel(…) on notifier("<name>"), which sends one payload for every recipient — or page the audience with backfill() from @ultimat3/jobs
|
X_NOTIFY_PUSH_DEVICE_GONE |
the push provider says a device token is dead | APNs answered 410 or FCM answered UNREGISTERED for a device token: the app was uninstalled, or the device rotated its token |
x jobs list --json — nothing to repair: the dead device row is already deleted, and the app stores its new token with its next pushRegister() call |
X_NOTIFY_PUSH_MESSAGE_INVALID |
a data-only push carries more than an id | the data of a data-only push names a reserved key, holds more than 8 keys, or a value longer than 256 characters |
pushChannel({ pusher, data: ({ event }) => ({ id: event.params.id }) }) — in the notifier: one id per push, the app fetches the rest over its API |
X_NOTIFY_PUSH_PROVIDER_REFUSED |
APNs or FCM refused a push for good | the provider refused the request and will refuse it again: a bad or revoked credential, a wrong topic or project, or a payload over its limit |
x jobs list --json — read meta.provider, meta.status and meta.reason on the failed step, then fix the credential (x secrets set ULTIMATE_APNS_PRIVATE_KEY) or the message |
X_NOTIFY_SMS_NUMBER_INVALID |
an SMS number is not E.164 | the number smsChannel() resolved for a recipient is not +, a country code and up to 15 digits in all (E.164) — a local spelling a provider guesses the country of is a message sent to a stranger | store numbers as E.164 (+4915112345678) and return that from smsChannel({ numberOf }) |
X_NOTIFY_SMS_TRANSPORT_MISSING |
an SMS was sent with no SmsTransport installed | smsChannel() delivered outside development and test, and apps//runtime.ts names no smsTransport — the memory transport would swallow the message, so the send is refused instead | add smsTransport: yourTransport() to apps/<app>/runtime.ts — behavesLike(smsTransportConformance, () => yourTransport()) proves it |
X_NOTIFY_STORE_MISSING |
a channel needs a store nothing installed | an in-app channel with no inbox store, a digest window with no digest store, or — in staging and production only — a delivery claim with no ledger. The ledger's memory default is one process's heap, so outside development and test it refuses rather than let a replay on another replica, or after a restart, send twice; the cli boot installs a Postgres ledger (x_notify_deliveries) when the app has a database, so this fires only for an app with none and no notifyStores.ledger. An inbox and a digest window have no default at all: there is nowhere to put the row, so they refuse rather than skip. Never an optional chain at the call site, because a silently skipped inbox write is a notification the user never sees and nobody logs. cause and meta.store name which store is absent |
export const runtime = { notifyStores: { inbox: memoryInboxStore(), digest: memoryDigestStore() } } in apps/<app>/runtime.ts — one object, naming every store this app wants: it is whole-object replacement and never a merge. postgresInboxStore({ executor }) shares the inbox across replicas |
notifier() is a job factory — one queue row and one step trace for the whole fan-out, with every recipient a durable step. Five of the seven codes are the app's own DECLARATION, one is somebody else's server and one is another attempt of the same run, which is what decides the statuses: the five are 500, X_NOTIFY_DELIVERY_FAILED is 502 and X_NOTIFY_DELIVERY_HELD is 409. That row is chosen for the day a notifier is invoked in a request rather than a job, and the asymmetry decides it — a wrong 502 costs nothing, and a wrong 500 pages the on-call for an email provider's outage, because stages.ts reports every status >= 500 to the error monitor.
Three of them are raised at notifier(...), while the app's modules load, so they fail the boot rather than a run: X_NOTIFY_CHANNELS_EMPTY, X_NOTIFY_CHANNEL_DUPLICATE, X_NOTIFY_DIGEST_UNSUPPORTED. The other four are raised inside the run.
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