Skip to content

Error Codes mail

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

Error codes: @ultimat3/mail

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

Clone this wiki locally