nbclient.exceptions.CellExecutionError: An error occurred while executing the cell

Not specified by the original author.

TL;DR

CellExecutionError means the code inside one cell raised an exception during a programmatic run (nbconvert, papermill, or your own nbclient script). Scroll past the nbclient wrapper to the original traceback at the bottom; that is the real error. Reproduce that single cell's code in a fresh kernel, fix the underlying bug, and re-run. Do not debug nbclient itself.

nbclient.exceptions.CellExecutionError: An error occurred while executing the cell

Use this when

• nbconvert --execute, papermill, or an nbclient script fails with CellExecutionError.
• The wrapped traceback names a specific cell number and an original exception type.
• Interactive runs of the same notebook behave differently than the automated run.

Not for this skill when

• The kernel will not start at all. That is a kernel/environment problem, not a cell error.
• Every cell fails identically. Suspect the environment, not the code.

Steps

1. Read the full traceback bottom-up to find the original exception type and message under the nbclient wrapper. Verify: you can name the real error.
2. Note the cell execution count or index nbclient reports. Verify: you know exactly which cell failed.
3. Copy that cell's source into a fresh notebook and run it alone. Verify: it fails the same way in isolation.
4. Fix the underlying error (missing file, bad parameter, import issue) in the source notebook. Verify: the isolated cell now passes.
5. Re-run the full programmatic execution. Verify: nbclient completes and the output notebook has outputs for every cell.

Variant phrasings

CellExecutionError nbconvert

The nbconvert phrasing. Same drill: read the wrapped traceback.

papermill CellExecutionError

The papermill phrasing. The parameters cell is a common culprit.

nbclient cell execution failed

Library-level phrasing. The cell raised; nbclient is the messenger.

Compatibility: nbclient 0.5+, nbconvert 6/7, papermill 2.x. The exception shape is stable across them.

Why it happens

nbclient executes cells by sending them to a kernel and re-raises whatever the kernel reports, wrapped in CellExecutionError with the cell attached. People new to programmatic execution debug the wrapper instead of the contents, but the wrapper adds no information beyond which cell failed. The fix is always in the cell's code or its inputs.

Edge cases / pitfalls

• Cells that depend on execution order or leftover variables pass interactively and fail under clean top-to-bottom execution. That is a notebook bug, not an nbclient bug.
• The default error output truncates long tracebacks. Rerun with full output to see the original exception.
• A cell that reads a file by relative path fails when the runner's working directory differs from your interactive one. Use absolute or anchored paths.

Provenance

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

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

Thread query: nbclient.exceptions.CellExecutionError: An error occurred while executing the cell

TL;DR: CellExecutionError means the code inside one cell raised an exception during a programmatic run (nbconvert, papermill, or your own nbclient script). Scroll past the nbclient wrapper to the original traceback at the bottom; that is the real error. Reproduce that single cell's code in a fresh kernel, fix the underlying bug, and re-run. Do not debug nbclient itself.

Not specified by the original author.

TL;DR

When papermill's parameter injection breaks a cell, the injected-parameters cell at the top of the output notebook shows exactly what values went in. Open the output notebook (it is written even on failure) and read that cell: a type mismatch (string where the code expects an int) or a missing key is usually staring at you. Fix the parameters YAML or add the parameters tag correctly, then re-run.

papermill execution failed: CellExecutionError in parameterized cell

Use this when

• Papermill fails with CellExecutionError and the traceback points at the parameters cell.
• The notebook runs fine interactively with hand-set values.
• You recently changed the parameters file or the tagged cell.

Not for this skill when

• Papermill hangs instead of failing. That is an infinite loop or blocking call.
• Parameters are silently ignored. That is a tagging problem.

Steps

1. Open the output notebook papermill wrote (it exists even on failure). Verify: you can see the injected-parameters cell.
2. Compare injected values against what the cell expects: types, keys, ranges. Verify: you spot the mismatch.
3. Check the source notebook has exactly one cell tagged parameters with defaults. Verify: the tag is present and spelled right.
4. Fix the parameters file (YAML types matter: quote strings, do not quote numbers) or the cell's assumptions. Verify: the file parses and types are right.
5. Re-run papermill. Verify: the run completes and the output notebook has executed outputs.

Variant phrasings

papermill parameters cell error

Short form. Read the injected cell in the output.

CellExecutionError papermill parameters

The exception phrasing. Type mismatch is the usual cause.

papermill injected parameters failed

General phrasing. Validate the YAML types.

Compatibility: papermill 2.x, nbclient 0.5+. The injected-parameters cell convention is stable.

Why it happens

Papermill inserts a new cell with your parameters right after the tagged defaults cell, and that cell is plain python: values come from YAML, so count: 10 is an int but count: "10" is a string. Notebook code written against hand-set defaults often assumes types the YAML does not provide, and the cell fails only under papermill, never interactively, which makes it look like a papermill bug.

Edge cases / pitfalls

• YAML silently coerces unquoted values (yes becomes True in YAML 1.1). Quote anything that must stay a string.
• Two cells tagged parameters make injection ambiguous. Keep exactly one.
• The output notebook is overwritten on each run. Copy it aside before re-running if you need the failure evidence.
• A parameters cell that also does work (not just assignments) runs twice in effect. Keep it to assignments only.

Provenance

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

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

Thread query: papermill execution failed: CellExecutionError in parameterized cell

TL;DR: When papermill's parameter injection breaks a cell, the injected-parameters cell at the top of the output notebook shows exactly what values went in. Open the output notebook (it is written even on failure) and read that cell: a type mismatch (string where the code expects an int) or a missing key is usually staring at you. Fix the parameters YAML or add the parameters tag correctly, then re-run.

Not specified by the original author.

TL;DR

For "nbconvert failed": run the export from the command line (not just the UI) so you see the full traceback, and read the first distinctive error: A.

nbconvert failed

When to use

You are seeing this: An export is two separate stages, executing the notebook, then converting the result, and each stage fails differently. Use this skill when you run into "Diagnose and fix nbconvert export failures (PDF, HTML, execution)".

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.

Use this when jupyter nbconvert --to pdf notebook.ipynb (or html, markdown, slides) fails, or when File > Download as errors with nbconvert failed. An export is two separate stages, executing the notebook, then converting the result, and each stage fails differently. Classify from the first error line, then fix that stage.

1. Classify: execution failure vs conversion failure

Run the export from the command line (not just the UI) so you see the full traceback, and read the first distinctive error:

A. CellExecutionError, or Timeout waiting for execute reply: the notebook itself fails to run. Fix the notebook first (step 2). Note: nbconvert does not execute by default, this failure only appears with --execute.

B. PandocMissing: "Pandoc wasn't found. ...": pandoc is missing or too old. nbconvert needs pandoc >= 2.9.2 and < 4.0.0.

C. OSError: "xelatex not found on PATH, if you have not installed xelatex you may need to do so. ...": PDF export needs a TeX distribution. Install one (step 3).

D. PDF creating failed, captured latex output: ... / Failed to run "..." command:: xelatex ran but the LaTeX compile failed. The captured output holds the real error, usually a missing LaTeX package or a LaTeX error from notebook content (step 4).

2. Execution failures: make the notebook run clean first

Reproduce the execution stage on its own:

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

• Timeout waiting for execute reply (30s): c.ExecutePreprocessor.timeout defaults to 30 seconds per cell. Long-running cells die at this limit; raise it in config or split the cell.

• Cells that legitimately raise: pass --allow-errors to keep executing and export the tracebacks.

• Rule out hidden state before blaming nbconvert: open the notebook and do Restart & Run All. A notebook that only works because of out-of-order cell execution will fail under nbconvert's clean top-to-bottom run.

3. Missing tools: pandoc and TeX

pandoc --version   # need >= 2.9.2, < 4.0.0
which xelatex

Install a TeX distribution (Debian/Ubuntu; see the nbconvert install docs for other platforms):

sudo apt-get install texlive-xetex texlive-fonts-recommended texlive-plain-generic

If xelatex is installed but nbconvert can't find it, common when exporting from the UI, whose server process has a different PATH than your shell, point nbconvert at it directly with the c.PDFExporter.latex_command config key (step 4).

4. LaTeX compile fails: read the captured output

The PDF creating failed, captured latex output text is the xelatex log. Read it for the actual error: most often a missing LaTeX package (install it with tlmgr, apt, or the MiKTeX console) or a LaTeX error triggered by notebook content such as unescaped special characters. To iterate faster than full PDF runs, export to LaTeX only and compile by hand:

jupyter nbconvert --to latex notebook.ipynb
xelatex notebook.tex

PDF export config keys (all settable in jupyter_nbconvert_config.py):

• c.PDFExporter.latex_command, default ["xelatex", "{filename}", "-quiet"]; override with an absolute path if xelatex is not on the server's PATH.

• c.PDFExporter.latex_count, how many times xelatex runs (default 3).
• c.PDFExporter.verbose, show the latex command output instead of capturing it.
• c.PDFExporter.texinputs, extra TEXINPUTS directory for local style files.

5. Useful non-PDF exports

jupyter nbconvert --to html --no-input notebook.ipynb   # hide code cells
jupyter nbconvert --to html --template lab notebook.ipynb
jupyter nbconvert --to markdown notebook.ipynb
jupyter nbconvert --to slides notebook.ipynb --post serve

--stdout pipes the output instead of writing a file.

6. Checklist for the failing export

1. Reproduce from the CLI to get the full traceback, not just the UI's nbconvert failed summary.

2. Classify: CellExecutionError/timeout vs PandocMissing vs xelatex-not-found vs LaTeX compile failure.

3. Execution: fix the notebook, use --allow-errors, or raise ExecutePreprocessor.timeout.

4. Tools: pandoc >= 2.9.2; texlive-xetex plus recommended fonts.

5. LaTeX: read the captured output; export --to latex and compile manually to iterate.

6. UI-only failures: compare PATH and config between your shell and the notebook server process.

Built from the nbconvert source (PDFExporter error strings for xelatex-not-found and LaTeX compile failure, PandocMissing version bounds, ExecutePreprocessor timeout default) and recurring Jupyter Discourse threads on PDF-via-LaTeX export failures.