Errors and limits

Error classes, exact codes, render-budget defaults, and when each failure occurs.

Configuration and asset setup can fail before rendering starts. Public render failures use NuxtPdfError and one code from PDF_ERROR_CODES.

Error classes and codes

Failure	Stage	Inspect or change
`TypeError`	Module setup	Read the message and correct the module option, template definition, local asset, or configured font. No render or template error code exists yet.
`PDF_TEMPLATE_NOT_FOUND`	Render dispatch	Check the template's relative filename and generated registry key.
`PDF_TEMPLATE_INVALID`	Template execution	Move `definePdf()` or `usePdfPageNumbers()` to its supported template/render scope.
`PDF_TREE_INVALID`	Vue mount or tree validation	Correct the named root, nesting rule, primitive prop, SVG reference, or text placement.
`PDF_LAYOUT_ERROR`	Layout	Check geometry and registered font family, weight, and style.
`PDF_LIMIT_EXCEEDED`	Any bounded render stage	Read the named limit and cap. Reduce the input or change that one configured budget.
`PDF_ASSET_INVALID`	Image admission	Replace invalid admitted PNG or JPEG bytes, dimensions, or declared format.
`PDF_ASSET_BLOCKED`	Image source or request policy	Check the source form, HTTPS allowlist, redirects, and per-hop timeout.
`PDF_RENDER_ERROR`	Render	Inspect the attached message and template identity for an uncategorized engine failure.

NuxtPdfError exposes code, templateKey, and, in development, templateFile. Its message names the template. Production leaves out the relative source path.

PDF_LIMIT_EXCEEDED covers every configured time and resource budget. An oversized local or remote image uses this code. Allowlist and unsupported-source policy failures use PDF_ASSET_BLOCKED. Invalid bytes that passed the source policy use PDF_ASSET_INVALID.

Render limits

Every field is an optional positive safe integer. Omitting the limits object or one field keeps the default below. Invalid configuration throws TypeError during module setup.

Field	Default	Bounded work
`timeoutMs`	`30_000`	Metadata resolution, mount, assets, every layout pass, serialization, and output collection.
`maxPages`	`2_000`	Laid-out page count.
`maxNodes`	`50_000`	Mounted document-tree nodes.
`maxTreeDepth`	`128`	Mounted document-tree depth.
`maxTextCharacters`	`2_000_000`	Unicode code points in text nodes.
`maxImages`	`256`	Image nodes.
`maxImageBytes`	`10_485_760`	Source bytes for one unique image.
`maxTotalImageBytes`	`33_554_432`	Source bytes across unique images.
`maxImagePixels`	`25_000_000`	Decoded pixels for one unique image.
`maxTotalImagePixels`	`100_000_000`	Decoded pixels across unique images.
`maxRemoteRequests`	`32`	Remote requests, including redirect hops.
`maxRemoteConcurrency`	`4`	Simultaneous remote requests.
`maxOutputBytes`	`67_108_864`	Completed PDF bytes.

Configure overrides in nuxt.config.ts:

nuxt.config.ts

export default defineNuxtConfig({
  pdf: {
    limits: {
      maxPages: 500,
      timeoutMs: 20_000,
    },
  },
})

The timeout is one deadline for the complete public render. It is checked between engine stages and cannot interrupt synchronous layout midway. A single stage can therefore finish after the deadline before the error is reported.

Tree and content limits are checked after Vue mounts and after each destination page-number update. Image budgets apply before engine admission. Output is collected into one completed buffer and discarded if maxOutputBytes is exceeded.

maxPasses is a per-template definePdf() option, not a module limit. Its default is 5. A table of contents normally settles after destination numbers feed into the next layout pass. Geometry that keeps changing fails with PDF_LIMIT_EXCEEDED.