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.

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.