Repository navigation
Error Codes mail
github-actions[bot] edited this page Nov 16, 2026
·
2 revisions
Part of Error codes: every code @ultimat3/mail registers. x errors explain <CODE> --json prints the same row.
| Code | Means | Typical cause | Fix |
|---|---|---|---|
X_MAIL_ADDRESS_INVALID |
an envelope address could restructure the SMTP command line | a to/cc/bcc/replyTo value carrying a control character, a mailbox with </>, or a non-ASCII mailbox (meta.reason: injection or non-ascii) — the envelope is built by interpolation and no SMTPUTF8 is negotiated. Refused by send() on every driver and by the queue schema alike, so a queued send can never fail at the worker for an address the inline path took |
pass a mailbox, bare or display-form: send(mail, data, { to: 'Ada <ada@example.test>', locale }). Never strip the break — an address is routing, and a rewritten one delivers somewhere else |
X_MAIL_CREDENTIAL_MISSING |
this deployment configured no mail transport | neither SMTP_URL nor RESEND_API_KEY is set outside development/test, so selectMailDriver installed a driver that refuses. The memory driver used to be installed there instead and reported accepted for mail that never left the process — password resets, receipts and invitations all "sent", none delivered, no error anywhere |
SMTP_URL="smtps://user:pass@host:465" MAIL_FROM="App <no-reply@yourdomain.test>" in the deployment environment, then restart — or RESEND_API_KEY=re_… in place of SMTP_URL. X_MAIL_DRIVER_UNAVAILABLE is the other half: that one is no driver installed — no mail: in apps/<app>/runtime.ts and no transport variable |
X_MAIL_DRIVER_UNAVAILABLE |
no mail driver is configured | no mail: in apps/<app>/runtime.ts and no transport variable set |
export const runtime = { mail: memoryMailDriver() } in apps/<app>/runtime.ts for dev, or set SMTP_URL (or RESEND_API_KEY) in .env so the boot selects a live driver |
X_MAIL_DUPLICATE |
two mails claim the same id | a copy-pasted defineMail
|
defineMail({ id: '<id>-2', ... }) — rename one of the two declarations; a layout: registerLayout('<name>-custom', myLayout)
|
X_MAIL_EVENT_INVALID |
a delivery notification is not a shape this receiver reads | too large, not UTF-8, not JSON, a missing envelope or notification field, or a bad timestamp (meta.problem says which) |
aws sns list-subscriptions-by-topic --topic-arn '<your topic arn>' — only the provider should post to this route |
X_MAIL_EVENT_PROVIDER_UNREACHABLE |
an SNS endpoint the receiver needed did not answer | the signing-certificate download or the subscription-confirm GET failed |
curl -sS -m 5 -o /dev/null https://sns.us-east-1.amazonaws.com/ — from the app host, with its region |
X_MAIL_EVENT_UNVERIFIED |
a delivery notification is not signed by its provider | no signature, a bad signature, a stale timestamp, a topic not in topicArns, a certificate URL off sns..amazonaws.com, or a SignatureVersion other than 1 or 2 (meta.reason says which) |
sesEventReceiver({ topicArns: ['<your topic arn>'] }) — or resendEventReceiver({ secret }) with the endpoint's whsec_ secret |
X_MAIL_HEADER_INVALID |
a header value carries a line break | interpolated data with a CR/LF reached Subject — header injection. meta.reason: 'non-ascii' is the other case: a non-ASCII mailbox in From/To/Cc/Reply-To reached the SMTP message builder |
reject the value at its own boundary — t.string().pattern(/^[^\r\n]*$/) on the field that feeds the header — then re-send. Never strip the break: a silently rewritten header hides the injection attempt |
X_MAIL_INBOUND_MALFORMED |
an inbound message is not MIME this parser reads | the provider delivered a message whose MIME structure is broken, truncated or uses a form the in-tree parser refuses |
x jobs list --state dead --json — the dead row names the problem; answer the sender out of band |
X_MAIL_INBOUND_TOO_LARGE |
an inbound message crosses a declared bound | an inbound message is larger, deeper, or carries more parts or attachments than inboundMail({ limits }) allows |
inboundMail({ limits: { maxBytes: 20_971_520 } }) — raise only the bound named in meta.limit |
X_MAIL_KEY_MISSING |
a mail rendered a key or slot with no value in its locale | send() resolved a catalog key the locale does not define, a catalog value still holding a placeholder, or a {slot} with no value, so nothing left |
x i18n sync <locale> — then translate the keys in meta.keys |
X_MAIL_LOCALE_MISSING |
send() was called without a locale |
a JS caller, or a cast that dropped the required field | send(mail, data, { to, locale: ctx.locale }) |
X_MAIL_PREVIEW_INVALID |
a mail's declared preview fails its own input schema | defineMail was given a preview the mail's input schema refuses, so the one render a person checks a template by is of data the mail can never be sent |
x mail preview <id> --json — names the field; then correct preview in the defineMail call to match input |
X_MAIL_PREVIEW_MISSING |
this mail declares no preview | x mail preview, or a render of every declared preview, was asked for a mail whose defineMail declares no preview data |
x mail preview <id> --json — then add preview: { ... } to that mail's defineMail call, shaped like its input |
X_MAIL_SEND_FAILED |
the mail transport refused the message | a rejected recipient, bad credentials, a throttle, a dead socket, or a peer that never completes a reply |
the queue now decides this without you: sendFailed carries the verdict as error.retry, so sendMailJob dead-letters a permanent refusal on the attempt that threw it instead of presenting the same rejected recipient four more times. meta.retryable is the same fact, unchanged, and is still what an operator reads. true → it will be requeued; false → fix what meta.stage names, then x doctor --json. meta.stage is the SendStage union in packages/mail/src/errors.ts: auth → SMTP_URL credentials, tls → openssl s_client -connect <host>:465 for the implicit-TLS certificate, starttls → openssl s_client -starttls smtp -connect <host>:587, recipient → the address, reply → point SMTP_URL at the SMTP port itself, since a proxy or an HTTP port answers like this |
X_MAIL_TEMPLATE_UNKNOWN |
no mail is registered under that id | the module holding defineMail({ id }) was never imported (also raised for an unregistered layout) |
export the defineMail and import it at boot |
X_MAIL_TEXT_MISSING |
the rendered mail has no plain-text part | a template of images and buttons only |
blocks.paragraph('mail.<id>.body') — a text-bearing block in that template |
X_MAIL_TRANSFORM_FAILED |
the app mail transform threw or returned no message | the transform hook failed, so the mail was not sent (never sent untransformed) |
setMailTransform((rendered, meta) => (meta.mailName === '<id>' ? track(rendered) : rendered)) — the hook must return { subject, html, text } strings for every mail it is handed |
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