Diagnose render failures

Use template attribution, preview diagnostics, and exact error messages to recover from a failed render.

First identify whether the failure happens during module setup or during render().

Setup validates configuration, template definitions, local images, and fonts. Invalid setup can throw TypeError before a template render exists.
Render failures use NuxtPdfError with a machine-readable code and templateKey. Development also includes the relative templateFile.

The errors and limits reference defines every code and default budget.

Inspect a render error

server/api/report.get.ts

import { NuxtPdfError, pdf } from '#pdf'

export default defineEventHandler(async () => {
  try {
    const result = await pdf.report.render(props)
    return result.response()
  }
  catch (error) {
    if (error instanceof NuxtPdfError) {
      console.error(error.code, error.templateKey, error.templateFile)
    }
    throw error
  }
})

Log identifiers and diagnostics through the application's normal error system. Do not log render props or document text unless the application has a separate data-handling policy for them.

Use the development preview

Open /_pdf/<template-key>. The preview renders through the same public template method as server code and shows duration, byte length, page count, layout passes, and registered font faces.

When a render fails, the preview keeps document content out of the error panel. It shows the code, template, relative source path, and a short message. If the previous render succeeded, the old PDF stays visible with a stale marker.

Match the message to a fix

Message or code	Inspect or change
`Cannot find module '#pdf'` or an untyped import	Run `pnpm nuxt prepare` or restart the development server.
`/_pdf` returns 404	Use the preview only in development. It is absent from production output.
`PDF_TEMPLATE_NOT_FOUND`	Check the relative filename and registry key. Nested keys retain `/`.
`PDF_TREE_INVALID`	Read the named primitive and prop or nesting rule. Remove DOM attributes and put text inside `PdfText`.
`Font family not registered`	Register the requested family, weight, and style in `pdf.fonts`.
A font throws `TypeError` during setup	Check its relative path, extension, signature, size, and location under `pdfs/fonts`.
`PDF_ASSET_BLOCKED`	Check the image source type, HTTPS allowlist, redirects, and timeout.
`PDF_ASSET_INVALID`	Replace the admitted bytes with a valid PNG or JPEG of the declared format.
`PDF_LIMIT_EXCEEDED`	Read the named limit and cap. Reduce the input or raise only that limit for a known document.

For maxPasses, fix layout that changes when destination page numbers appear. Raising the cap does not make unstable geometry converge. See the table-of-contents guide.

Monitor successful renders

Every completed result includes immutable metadata and diagnostics. Record duration, output bytes, page count, layout passes, layout warnings, and registered font faces.

The development preview explains each layout warning. For example, an unbreakable PdfView that is taller than the page can render with overflow; the preview names the page, node type, node height, and usable page height. This is a warning rather than a render failure because the output is still a valid PDF and some authors intentionally use oversized pages. The failure shows up in a customer's invoice, not a test run. Alert on trends before time or output budgets become routine failures.