agent's voila dashboard build failed: template dependency missing from the image

TL;DR

Voila renders through named templates, and if the template package is not installed in the serving image the build fails at template resolution, not at notebook execution. Add the template package (for example voila-gridstack or the lab-based template you use) to the image's requirements and rebuild the image. Then verify with voila --template=[name] --no-browser against a smoke notebook before the dashboard goes live.

agent's voila dashboard build failed: template dependency missing from the image

Use this when

• Voila fails at startup with an error naming a template that cannot be found or loaded.
• The dashboard builds on a laptop but fails in the deployment image.
• An agent generated the Dockerfile or requirements without the template package.

Not for this skill when

• Voila serves but the dashboard looks wrong. That is a template content or widget issue, not a missing dependency.
• A notebook cell raises inside the Voila render. That is an execution error in the notebook code.

Steps

1. Read the failure: the Voila log names the missing template or the import that failed. Expected: you know the exact template package name.
2. Check the image build files (requirements.txt, environment.yml, Dockerfile) for that package. Expected: confirmed absent, which explains the laptop-vs-image split.
3. Add the template package with a pinned version to the image requirements and rebuild the image. Expected: the build log shows the template package installing cleanly.
4. Smoke-test the template: voila --template=[name] --no-browser --port 8866 /tmp/smoke.ipynb using a tiny notebook. Expected: Voila starts and serves without template errors.
5. Run the real dashboard notebook through the same command. Expected: the dashboard renders with the intended template styling.
6. Lock the recipe: keep the template pin next to the Voila pin in the image spec so the next rebuild does not drift. Expected: the image spec lists both pins explicitly.

Tool compatibility

Voila 0.5.x; template packages such as voila-gridstack; Jupyter server 2.x; Docker/OCI image builds.

Variant phrasings

voila template not found docker image

The container phrasing. The template package must be in the image requirements.

voila failed to load template

The load phrasing. Pin and install the template package, then rebuild.

voila dashboard build missing dependency

The general phrasing. Diff the laptop env against the image env to find the gap.

Why it happens

Voila separates the notebook from its presentation: templates are separate installable packages that the server resolves by name at startup. Agents building deployment images tend to copy the notebook and the data requirements but forget the presentation layer, because nothing in the notebook file itself declares which template it needs. The laptop works because the developer installed the template months ago and forgot. The fix is to treat the template as a first-class dependency with a pin, exactly like any Python package, and to smoke-test template resolution in the image rather than assuming it.

Edge cases / pitfalls

• Some templates pull specific JupyterLab or ipywidgets versions. Pin the template together with Voila to avoid a transitive conflict.
• --template accepts a name, not a path. A local template directory needs proper packaging or the template_paths config, not just a name.
• Testing with --no-browser still executes the notebook. A smoke notebook with no heavy cells keeps the test fast.
• Custom CSS overrides in the notebook directory do not travel with the template. Keep them in the image too, or they silently vanish in deploy.

Provenance

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