nbclient "DeadKernelError: Kernel died" in CI

nbclient (used by nbconvert and papermill) talks to a kernel subprocess. If that process exits unexpectedly while a cell is running, nbclient detects the dead channel and raises DeadKernelError. The most common cause in CI is the OS killing the kernel for using too much memory.

What this error means

A notebook run fails with "nbclient.exceptions.DeadKernelError: Kernel died" mid-execution, sometimes after a cell that allocates a large array or model.

nbclient.exceptions.DeadKernelError: Kernel died

Common causes

The kernel was OOM-killed

A cell allocated more memory than the runner has, so the OS killed the kernel process and nbclient saw the channel die.

A native extension crashed the process

A segfault in a C extension (numpy/torch/native lib) terminates the kernel abruptly, which nbclient reports as a dead kernel.

How to fix it

Reduce memory or use a larger runner

1. Check whether the failing cell allocates large data or models.
2. Lower batch/data size for CI, or run on a higher-memory runner.
3. Re-run and confirm the kernel survives the cell.

Allow nbclient to restart on a dead kernel

Permit a limited number of automatic restarts so a transient crash does not immediately fail the whole notebook.

jupyter nbconvert --to notebook --execute \
  --ExecutePreprocessor.kernel_name=python3 notebook.ipynb

How to prevent it

• Keep CI notebook memory usage well under the runner limit.
• Pin native extension versions to avoid known crash regressions.
• Run memory-heavy notebooks on appropriately sized runners.

Related guides