nbconvert "CellExecutionError" during --execute in CI

nbconvert --execute runs each cell through nbclient's ExecutePreprocessor. By default it stops at the first cell that raises and re-emits that exception as a CellExecutionError, echoing the failing source and the original traceback.

What this error means

jupyter nbconvert --to notebook --execute exits non-zero with "nbclient.exceptions.CellExecutionError: An error occurred while executing the following cell", showing the cell source and the inner exception.

nbclient.exceptions.CellExecutionError: An error occurred while executing the following cell:
------------------
df = load_data("data.csv")
------------------
FileNotFoundError: [Errno 2] No such file or directory: 'data.csv'

Common causes

A real bug or missing input in a cell

The notebook genuinely fails: a missing data file, an unset environment variable, or a code error that only shows up in the clean CI environment.

Environment differences from local

Different package versions, missing credentials, or absent files cause a cell that passes locally to raise in CI.

How to fix it

Read the echoed cell and inner traceback

1. Find the failing cell source printed between the dashed lines.
2. Read the inner exception (the last traceback line) for the real cause.
3. Fix the data path, environment, or code that the cell depends on.

Allow errors only where intentional

If a cell is meant to demonstrate an error, tag it so nbconvert continues instead of failing the whole run; do not blanket-ignore all errors.

jupyter nbconvert --to notebook --execute \
  --ExecutePreprocessor.allow_errors=False notebook.ipynb

How to prevent it

• Run notebooks in a clean environment locally before pushing.
• Commit or fetch required data files so cells find their inputs in CI.
• Keep dependency versions pinned so behavior matches across machines.

Related guides