Hex dashboard cell failed: Python kernel error in notebook report fix

Not specified by the original author.

TL;DR

Run the project from the top and fix the failing cell in context. Hex Python cells share a kernel and pass dataframes between cells, so a kernel error often starts upstream, a missing package, a dataframe that changed shape, or memory pressure from an earlier cell. Restart the kernel, confirm the failing cell inputs, install the pinned package versions the project expects, and rerun the full sequence.

Hex dashboard cell failed: Python kernel error in notebook report fix

Use this when

• A Hex project app or scheduled run fails and the log names a Python cell and a kernel error.
• The cell runs alone in a fresh session but fails in the full project sequence, or the reverse.
• A package was upgraded or an upstream SQL cell changed recently.

Not for this skill when

• The failing cell is a SQL cell erroring on the warehouse. Debug the SQL and warehouse connection instead.
• Every Hex project in the workspace fails at once. Check the Hex platform status before one project environment.

Steps

1. Open the project in edit mode and run cells in order from the top, noting the first cell that errors. Verify: the first failing cell is identified rather than only the last reported one
2. Read the full kernel traceback for that cell and note the exception type, such as a missing module, a missing column, or a memory error. Verify: the traceback names a concrete cause to act on
3. Restart the kernel and rerun the sequence to clear state left by earlier partial runs. Verify: a clean run reaches the same failing cell or passes it
4. Fix the named cause, installing the pinned package version in the project environment, correcting the column reference, or reducing the data an earlier cell loads. Verify: the previously failing cell completes after the fix
5. Run the whole project end to end in app order and confirm every downstream cell and chart updates. Verify: a full run completes with no cell in an error state
6. Publish the fixed version and, if the project is scheduled, confirm the next scheduled run succeeds. Verify: the run history shows a successful complete run

Why it happens

Notebook state is both the power and the hazard of the format. Cells that pass in isolation fail in sequence because the kernel carries real intermediate state, and published apps freeze one version of that sequence for viewers. Running the full order before publishing, and pinning the project package environment, are the two habits that keep the published behaviour equal to the tested behaviour.

A Hex project is an ordered notebook where SQL and Python cells feed each other and the published app renders the results. The Python kernel holds state across cells, so the cell that reports the error is frequently not the cell that caused it. Kernel restarts, package version drift in the project environment, and an upstream SQL cell returning a renamed column are the recurring triggers, and the app view hides most of that context behind one failed cell.

Field notes for Hex specifically. The project run history, the cell level logs, and the published app version together define what actually ran, and they often disagree with what the editor last showed, because publishing freezes a version. Always debug against the failing run version of the project rather than the current edit buffer, or you may fix a cell that was never the problem. Kernel state also means the run order in the app, not the order an author clicked through while exploring, is the sequence that must pass before publishing.

For Hex teams, the publishing checklist is the reliability tool. Run the project top to bottom in a fresh kernel, check the app view as a viewer rather than in edit mode, and only then publish or rely on the schedule. Projects that skip the fresh kernel run ship state dependent notebooks that fail for the scheduler at night. Pinning the project package environment and noting the pins in the project description closes the other common gap, where a library update quietly changes a cell result between two scheduled runs.

Variants and edge cases

Hex Python cell kernel error project run failed fix

The direct phrasing from the run log.

Hex notebook cell works alone fails in sequence state

The sequence variant where kernel state is the cause.

Hex app scheduled run Python cell missing package

The environment variant for package drift in the project.

Provenance

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

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

Thread query: Hex dashboard cell failed: Python kernel error in notebook report fix

TL;DR: Run the project from the top and fix the failing cell in context. Hex Python cells share a kernel and pass dataframes between cells, so a kernel error often starts upstream, a missing package, a dataframe that changed shape, or memory pressure from an earlier cell. Restart the kernel, confirm the failing cell inputs, install the pinned package versions the project expects, and rerun the full sequence.

Not specified by the original author.

TL;DR

Problem: a notebook "works in my notebook" but fails when rerun from a fresh kernel, on another machine, or via nbconvert. Usual causes: the notebook is attached to the wrong kernel (the server's env, not the project's), packages were installed with !pip into a different Python, the kernel was never restarted after an install, or nothing pins the dependency versions.

When to use

You are seeing this: A Jupyter kernel is a separate process. Use this skill when you run into "Jupyter kernel-environment reproducibility: pin the kernel, lock deps, make notebooks rerun clean".

When not to use

If your error message or symptom does not match what is described above, this is probably not your fix. Search for your exact error text instead of forcing this one to fit.

Versions

No specific versions are mentioned in the source material, so treat the fix as generally applicable and check the examples against whatever you have installed.

Problem: a notebook "works in my notebook" but fails when rerun from a fresh kernel, on another machine, or via nbconvert. Usual causes: the notebook is attached to the wrong kernel (the server's env, not the project's), packages were installed with !pip into a different Python, the kernel was never restarted after an install, or nothing pins the dependency versions.

1. Pin the notebook to a real environment

A Jupyter kernel is a separate process. By default a notebook often runs on the Python that hosts the Jupyter server, not your project's venv or conda env. Register your environment as a named kernel:

# Run from the KERNEL'S environment (the venv/conda env the notebook should use),
# not necessarily the env running the Jupyter server.
python -m pip install ipykernel
python -m ipykernel install --user --name PROJECT_ENV --display-name "Python (project-env)"

• --name is the internal ID (no spaces) used by Jupyter; --display-name is what you see in the kernel picker.
• Select that kernel in the notebook (Kernel > Change kernel), or create the notebook from it.
• Inspect and remove stale kernelspecs:

  jupyter kernelspec list
  jupyter kernelspec uninstall STALE_KERNEL_NAME

• Sanity check from inside a cell: import sys; print(sys.executable) should point at your project's Python.

2. Install packages into the kernel's environment

Inside a notebook cell, use the %pip magic, never !pip:

%pip install package-name

• %pip installs into the environment backing the running kernel.
• !pip runs the shell's pip, which may resolve to a different Python (e.g. the notebook server's env). The install "succeeds" but import still fails in the notebook.

3. Restart the kernel after installing anything

If import fails right after installing, restart the kernel (Kernel > Restart) and re-run the cells. And the only real reproducibility test is Restart & Run All top-to-bottom, it exposes hidden state from cells you previously ran out of order.

4. Lock the environment so someone else can recreate it

For pip/venv projects:

pip freeze > requirements.txt   # exact pins of everything installed
pip install -r requirements.txt # recreate elsewhere

For conda:

conda env export > environment.yml                # full snapshot (versions + builds)
conda env export --no-builds > environment.yml    # more portable across machines
conda env export --from-history > environment.yml # only the packages you asked for
conda env create -f environment.yml
conda activate ENV_NAME

• Check requirements.txt / environment.yml in next to the notebook.
• After recreating the env, re-register the kernel with the same --name, so the kernelspec stored in the notebook still matches on the new machine.

5. nbconvert execution gotchas when sharing

Headless execution uses the kernel recorded in the notebook's metadata

jupyter nbconvert --to notebook --execute NOTEBOOK.ipynb

• The kernel name comes from the notebook metadata. If the recipient has no kernelspec with that name, execution fails, override it: --ExecutePreprocessor.kernel_name=PROJECT_ENV.
• Per-cell timeout defaults to 30 seconds; raise it (--ExecutePreprocessor.timeout=600) or disable with -1 for long jobs.
• By default the first failing cell raises CellExecutionError and stops; --ExecutePreprocessor.allow_errors=True records errors in the output and continues.
• Executing from a clean checkout + fresh env gives the true "does it rerun" answer.

Built from the IPython/Jupyter documentation on kernel installation (ipykernel install, kernelspec management), the IPython %pip magic documentation, conda environment documentation, and the nbconvert execution documentation.

Not specified by the original author.

TL;DR

Install ipykernel into the same Python environment that runs the voila command. Voila launches kernels from its own environment; if ipykernel is not installed there, every kernel start fails. Run pip install ipykernel in that environment (or conda install ipykernel) and restart Voila.

voila kernel died on dashboard start: missing ipykernel in the voila env

Use this when

• The Voila page loads but shows kernel died or kernel failed to start
• The notebook runs fine in JupyterLab from a different environment
• The Voila server log shows No module named ipykernel or kernelspec errors

Not for this skill when

• Voila returns 404 before any kernel starts - that is item 106
• Websocket connections are rejected with 403 - that is item 108
• The kernel starts but the notebook code raises - that is a notebook content problem

Steps

1. Confirm which Python runs Voila: which voila and voila --version, then check python -c import of ipykernel in that interpreter. Expected: the import fails, proving ipykernel is absent from the Voila env.

2. Install it: pip install ipykernel (or conda install ipykernel) using the same interpreter that runs voila. Expected: the install completes and the import now succeeds.

3. Register the kernelspec if needed: python -m ipykernel install --name [env name] --user. Expected: jupyter kernelspec list shows the new kernel.

4. Restart the Voila server so it picks up the new environment. Expected: the server log shows a clean start with no import errors.

5. Open the dashboard. Expected: the kernel starts, cells execute, and outputs render instead of the kernel-died message.

Tool compatibility

Voila 0.4.x / 0.5.x, ipykernel 6.x, Python 3.9+, pip or conda

Variant phrasings

voila kernel died on startup

Same fix applies: see the Steps section above.

voila no module named ipykernel

Same fix applies: see the Steps section above.

voila dashboard kernel failed to start

Same fix applies: see the Steps section above.

Why it happens

Voila is a kernel client: it asks the local Jupyter machinery to start a kernel using a kernelspec, and the default python3 kernelspec resolves to the interpreter in Voila's own environment. Minimal Voila installs (pip install voila without the kernel extras) lack ipykernel there, so the kernelspec points at an interpreter that cannot provide a kernel and every start dies instantly. Installing ipykernel into the serving environment gives the kernelspec a working kernel to launch.

Edge cases / pitfalls

• Kernelspecs pointing at deleted conda envs fail the same way; check jupyter kernelspec list paths.
• In containers, install ipykernel in the image build, not at container start, or restarts reintroduce the failure.
• A kernel that starts then dies on import is a package problem in the notebook env, not this issue.

Provenance

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

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

Thread query: voila kernel died on dashboard start: missing ipykernel in the voila env

TL;DR: Install ipykernel into the same Python environment that runs the voila command. Voila launches kernels from its own environment; if ipykernel is not installed there, every kernel start fails. Run pip install ipykernel in that environment (or conda install ipykernel) and restart Voila.