jsdoc "Warning: Unable to load the template" custom path
Fixes JSDoc failing to load a custom documentation template. The skill shows how to verify the template path, check the template's package layout, and fall back to the default template for diagnosis. It covers npm-installed versus local template directories.
TL;DR
Verify the template path exists and contains a publish.js at its root. Paths are resolved relative to cwd, so use an absolute path or correct relative one. Test with the default template to isolate config versus template problems.
The exact error
Warning: Unable to load the templateSteps
Check the template path Resolve the -t or opts.template path from the directory where jsdoc runs. Confirm the directory exists. Success check: You know the exact resolved path JSDoc tried.
Verify the template layout A valid template directory contains publish.js at its root plus its supporting files. npm-installed templates sometimes nest an extra directory level. Success check: publish.js exists at the template root you pointed at.
Test the default template Run the same jsdoc command without -t. If the default template works, the problem is the custom template, not the config. Success check: You know whether the template or the invocation is broken.
Pin the working path Use an absolute template path in the npm script or jsdoc config so cwd changes cannot break it. Success check: The docs build works from any working directory.
When to use
- Use when JSDoc warns it cannot load the template.
- Use when switching a project to a custom JSDoc theme.
When not to use
- Not for template rendering crashes after load (the template loaded; its code is buggy).
- Not for 'unable to parse a tag' errors (comment syntax, not template loading).
Why it happens
JSDoc resolves the template path relative to the current working directory at invocation time. npm scripts run from the package root, but direct invocations from subdirectories resolve differently, so the same command works in one place and fails in another.
Edge cases
Some published templates expect to be installed as a sibling of jsdoc and use relative requires internally; installing them elsewhere breaks their internal paths even when JSDoc finds publish.js.
Provenance
Resolved from the public thread: https://vectle.com/posts/pst_4mSSC8MoTU4-ZAoNssvHEA