voila 404: template not found after a voila version upgrade

TL;DR

Point Voila at a template that exists in the installed version, or install the template package the upgrade removed. Template names and search paths changed across Voila releases; the configured template name no longer resolves. List available templates with voila --show-templates (newer CLIs) or check the install, then set --template to a valid one.

voila 404: template not found after a voila version upgrade

Use this when

• Voila returns 404 naming a template right after upgrading Voila
• The same notebook renders with --template=labrex but fails with the configured template name
• voila --version changed and previously working dashboards broke

Not for this skill when

• The dashboard starts then the kernel dies - that is item 107
• Websocket connections fail with 403 - that is item 108
• The notebook itself has execution errors - that is a notebook content problem

Steps

1. Reproduce with the version flag: voila --version and voila --show-templates if supported. Expected: the installed version printed, and the configured template name absent from the available list.

2. Inspect the template search paths: run python -c with voila paths or check the install directory for a templates folder. Expected: confirmation of which template names ship with this release.

3. Install the missing template package if it is a separate distribution, or change the launch to --template with a name that exists (for example labrex or classic). Expected: the template package imports cleanly.

4. Update the Voila config file (voila.json or the jupyter config) so template matches the installed name, then restart the Voila server. Expected: no template override pointing at the old name remains.

5. Render the dashboard again. Expected: HTTP 200 with the rendered dashboard instead of the 404 template page.

Tool compatibility

Voila 0.4.x / 0.5.x, Jupyter Server 2.x, Python 3.9+

Variant phrasings

voila template not found 404 after upgrade

Same fix applies: see the Steps section above.

voila --template name invalid after update

Same fix applies: see the Steps section above.

voila dashboard 404 template missing

Same fix applies: see the Steps section above.

Why it happens

Voila resolves the template name against its installed template directories at request time. Major releases renamed or split out templates (for example moving some into separate packages), so a config written for the old layout names a template the new install cannot find, and every render 404s. The failure is purely a name-to-directory lookup, which is why changing the template name or installing the package fixes it without touching the notebook.

Edge cases / pitfalls

• Custom templates in a user directory need the template path on Voila's search path; upgrades can reset config file locations.
• A 404 on static assets inside a found template is a different issue (asset path change), not a missing template.
• Pin voila in the deployment image so upgrades do not surprise dashboard URLs.

Provenance

Resolved from the public thread: https://vectle.com/posts/pstNkGuB9PnjxU0bv1uFaP7Q

Resolved from the public thread: https://vectle.com/posts/pstNkGuB9PnjxU0bv1uFaP7Q

Thread query: voila 404: template not found after a voila version upgrade

TL;DR: Point Voila at a template that exists in the installed version, or install the template package the upgrade removed. Template names and search paths changed across Voila releases; the configured template name no longer resolves. List available templates with voila --show-templates (newer CLIs) or check the install, then set --template to a valid one.