Troubleshooting

Template renders empty content

By default (pdf.templates.throwOnMissing: false), requesting a template key that was never registered logs a PDF template not found: <key> warning and returns { content: [] } instead of throwing. Set pdf.templates.throwOnMissing to true to fail loudly instead.

Template changes not picked up

PdfTemplatesStore.get() serves the cached, parsed definition by default. Set pdf.templates.disableCache to true to reload from disk on every access, or call PdfTemplatesStore.reload(template?) explicitly (with no argument to reload every loaded template).

Setting a template that already exists

PdfTemplatesStore.set(name, definition, { replace: false }) throws PDF template already exists: <name> if a template with that key is already registered. Use replace: true (the default) or PdfTemplatesStore.upsert(...) to overwrite intentionally.

Circular template inheritance

renderPdfTemplate/resolveTemplateDefinition throw Circular PDF template inheritance detected: <template> when a template's extends chain refers back to a template already being resolved.

Unsupported template file format

PdfTemplatesStore.load(module, folder) only parses .json, .yml, and .yaml files; any other extension inside the folder throws Unsupported template format: <filename>.

Common Errors

@quik/pdf has no locale file of its own — template resolution and store errors above are plain Error instances (not translated quik.errors.pdf.* keys).