Error types

Public error classes, their stable fields, common symptoms, and recovery steps.

Nuxt Email exposes five runtime error classes from @lupinum/nuxt-email/errors. Original render failures remain available through cause.

Public errors

Error	When it occurs	Stable fields	What to do
`EmailRenderError`	Loading, prop validation, Vue server rendering, document validation, or plain-text conversion fails.	`templateName`; original failure on `cause`	Log the error and inspect `cause`. Fix the template, props, or document named by `templateName`.
`UnknownEmailTemplateError`	An untyped runtime name is absent from the generated registry.	`requestedName`; sorted `knownNames`	Use one of `knownNames`, or add the template and run `nuxt prepare`.
`TailwindMissingHeadError`	A Tailwind media-query or pseudo-class rule has no `<head>` inside its `ETailwind` boundary.	Message names the affected classes.	Move `EHead` inside `ETailwind`, or remove the classes that require head CSS.
`DefineEmailOutsideRenderError`	`defineEmail()` runs outside an email render.	Error identity and message	Call it from an email template rendered by Nuxt Email.
`DuplicateEmailDefinitionError`	One render calls `defineEmail()` more than once.	Error identity and message	Keep one call and combine its `subject` and `text` metadata.

EmailRenderError.templateName is the registry name for renderEmail(). Standalone rendering uses the Vue component name. There is no componentName compatibility alias.

Find an error by symptom

Search phrase or symptom	Error	Next check
Template not found, unknown template, or unknown email	`UnknownEmailTemplateError`	Compare `requestedName` with `knownNames`. Nested names use `/` and omit `.vue`.
Missing head, `<head> not found`, or Tailwind variant failure	`TailwindMissingHeadError`	Confirm that `EHead` is inside the same `ETailwind` boundary.
`defineEmail` outside render	`DefineEmailOutsideRenderError`	Keep the call in the template's `<script setup>`.
Duplicate email definition	`DuplicateEmailDefinitionError`	Search the template and its setup path for a second call.
Render failed, invalid document, or invalid props	`EmailRenderError`	Inspect `error.cause`; it preserves the underlying failure.

There is no TemplateNotFoundError. The public class for that condition is UnknownEmailTemplateError.

Imports

import {
  DefineEmailOutsideRenderError,
  DuplicateEmailDefinitionError,
  EmailRenderError,
  TailwindMissingHeadError,
  UnknownEmailTemplateError,
} from '@lupinum/nuxt-email/errors'

EmailRenderError is also exported by @lupinum/nuxt-email/testing. The two metadata errors are also exported by @lupinum/nuxt-email/define-email.

Template discovery can report DuplicateEmailTemplateError or EmailTemplateDiscoveryError during module setup. These are diagnostics, not exports from the public error entry point.

Log the full error on the server, including cause. Return a generic response to the caller. Nuxt Email does not serialize filesystem paths or stacks into production responses. The development preview shows richer local details for authoring.

server/api/welcome.get.ts

export default defineEventHandler(async () => {
  try {
    return await renderEmail('welcome', props)
  }
  catch (error) {
    console.error(error)
    throw createError({ statusCode: 500, statusMessage: 'Email render failed' })
  }
})

Error types

Public errors

Find an error by symptom

Imports

Production handling