Skip to content

Error Codes notify

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

Error codes: @ultimat3/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

Notes

Notifications

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.

Clone this wiki locally