Error types

The typed errors Nuxt Email throws, the stable fields each carries, and when each occurs.

Nuxt Email's errors are intentionally small and actionable. Each is a named Error subclass carrying stable, structured fields, and original failures are preserved through cause.

Render and lookup errors

Error	When it occurs	Stable fields
`EmailRenderError`	Component loading, prop validation, Vue SSR, document validation, or plain-text conversion fails.	`componentName` (the registry template name); original failure on `cause`.
`UnknownEmailTemplateError`	An untyped runtime name is not in the generated registry.	`requestedName`; sorted `knownNames`; a message naming both.
`DuplicateEmailTemplateError`	Two discovered paths normalize to one template name.	`templateName`; sorted `sourcePaths`.
`EmailTemplateDiscoveryError`	Template discovery cannot inspect a source path.	`sourcePath`; underlying `cause`.
`TailwindMissingHeadError`	Non-inlinable Tailwind rules have no `<head>` inside their `ETailwind` boundary.	Message names the offending classes.

EmailRenderError wraps document-completeness failures too: a template that does not render exactly one <html> root and one <body> fails here with the underlying document error preserved as cause.

defineEmail error

Error	When it occurs
`DefineEmailOutsideRenderError`	`defineEmail()` is called outside an email render (for example from ordinary application code rather than a template rendered by `renderEmail`).
`DuplicateEmailDefinitionError`	One email render calls `defineEmail()` more than once.

Import supported runtime errors from @lupinum/nuxt-email/errors. EmailRenderError is also re-exported by @lupinum/nuxt-email/testing for unit tests. Template discovery errors are module-setup diagnostics rather than part of the public runtime error subpath.

The public error subpath exports EmailRenderError, UnknownEmailTemplateError, DefineEmailOutsideRenderError, DuplicateEmailDefinitionError, and TailwindMissingHeadError.

Handling errors in production

Original stack information is preserved through cause. Your HTTP handlers decide how much detail to expose — Nuxt Email does not serialize filesystem paths or stacks into a production response. The development preview returns richer local error detail for authoring, including the wrapped EmailRenderError stack and its cause.

server/api/welcome.get.ts

export default defineEventHandler(async () => {
  try {
    return await renderEmail('welcome', props)
  }
  catch (error) {
    // Log the full error server-side; return a generic message to the client.
    console.error(error)
    throw createError({ statusCode: 500, statusMessage: 'Email render failed' })
  }
})