Diagnosing Jupyter Kernel Start Failures: A Step‑by‑Step Guide

Problem: Notebook Opens but the Kernel Is Dead

You launch Jupyter Notebook, the dashboard loads, and a notebook file opens. The kernel indicator shows Dead or Kernel died, restarting. No code executes, and the only feedback is a brief flash of the restart animation.

Quick Symptom‑Cause Reference

Observed symptom	Most likely cause
Kernel status = Dead / restarting	Missing ipykernel in the selected Python environment or kernel spec points to a deleted interpreter
Browser cannot reach the server (connection refused)	Port 8888 already in use or firewall blocking localhost
Kernel starts then dies on first import	Incompatible binary package (e.g., NumPy, SciPy) or corrupted Conda/virtualenv environment
Token/password rejected	Hashed token mismatch or config pointing to a different profile directory
Long‑running cells produce no output	WebSocket disconnected by proxy/reverse‑proxy timeout
No such kernel error on old notebook	Kernel JSON spec missing from share/jupyter/kernels or environment removed

Ordered Diagnostic Checks

1. Confirm the kernel spec exists and points to a live interpreter

   Run the following in the same shell where you start Jupyter (no elevated privileges required):

   jupyter kernelspec list

   Expected output includes a line such as:

   python3    /home/alice/.local/share/jupyter/kernels/python3

   Inspect the kernel.json inside that directory:

   cat /home/alice/.local/share/jupyter/kernels/python3/kernel.json

   Verify the argv array references a Python executable that exists (which python3 should match). If the path is missing, the spec is broken.

2. Isolate the environment with a minimal notebook

   Start a temporary server on a free port and create a notebook that only runs print(1):

   jupyter notebook --no-browser --port 8889 --NotebookApp.token=''

   Open http://localhost:8889, create a new notebook using the suspect kernel, and execute a single cell containing print(1). If this succeeds, the kernel binary works; the failure in your original notebook is likely due to user code or a corrupted package.

3. Examine server logs for kernel launch errors

   Restart the server with debug logging:

   jupyter notebook --log-level=DEBUG 2>&1 | tee jupyter-debug.log

   Search the log for lines containing KernelRestarter, KernelManager, or tracebacks. Typical entries:

   • FileNotFoundError: [Errno 2] No such file or directory: '/opt/conda/envs/myenv/bin/python' – interpreter missing.
   • ImportError: libopenblas.so.0: cannot open shared object file – broken binary dependency.

4. Validate the Python environment used by the kernel

   Activate the environment referenced in kernel.json and ensure ipykernel is installed:

   source /opt/conda/envs/myenv/bin/activate
   python -m pip show ipykernel

   If the package is absent, install it (pip install ipykernel) and re‑register the kernel:

   python -m ipykernel install --user --name=myenv --display-name "Python (myenv)"

5. Check WebSocket connectivity when output stalls

   Open the browser developer tools (F12), go to the Network tab, filter for WS. A healthy kernel shows a persistent WebSocket connection with status 101 Switching Protocols. If you see 1006 (abnormal closure) or repeated 404 on /api/kernels/<id>/channels, a reverse proxy (nginx, Apache) or firewall is likely terminating idle connections.

   Typical nginx fix: increase proxy_read_timeout and proxy_send_timeout to at least 3600s, and ensure proxy_http_version 1.1; with proxy_set_header Upgrade $http_upgrade; and proxy_set_header Connection "upgrade";.

Targeted Fixes Linked to Findings

Finding	Fix	Risk / Note
Kernel spec points to missing interpreter	Edit or recreate kernel.json with a valid argv path, then restart Jupyter server.	Do not edit while server runs; restart required.
ipykernel not installed in environment	Install ipykernel and re‑register the kernel (see step 4).	Installing into base environment affects all kernels; prefer per‑env install.
Corrupted Conda/virtualenv (binary import error)	Recreate the environment from a clean environment.yml or requirements.txt.	Backup any custom packages before destruction.
Port 8888 occupied	Stop the conflicting process (lsof -ti:8888 | xargs kill) or start Jupyter on another port (--port 8890) and update any reverse‑proxy config.	Changing port requires firewall/proxy rule updates.
WebSocket timeout behind proxy	Adjust proxy timeouts and enable WebSocket upgrade headers (see step 5).	Incorrect proxy config can break other services; test in staging first.
Missing kernel spec (No such kernel)	Run jupyter kernelspec install /path/to/kernel_dir --user or reinstall the environment which registers the spec automatically.	Spec files are read at server start; restart after installation.

Escalation Criteria

• After completing steps 1‑5 the kernel still dies on print(1) – indicates a deeper OS‑level issue (e.g., SELinux/AppArmor denying exec, filesystem corruption). Engage system administrator.
• Multiple kernels across different environments fail simultaneously – suspect a shared library mismatch (e.g., libpython version) or a broken Jupyter installation. Consider reinstalling Jupyter in a clean virtualenv.
• WebSocket errors persist despite proxy tuning – capture tcpdump/Wireshark trace to verify intermediate network devices (load balancers, VPN) are not stripping upgrade headers.

Verification Checklist

1. Run jupyter kernelspec list – the problematic kernel appears with a valid path.
2. Launch the minimal notebook on a fresh port – print(1) executes and output appears instantly.
3. Server log shows no KernelRestarter errors for the test kernel.
4. Browser dev tools show a stable WebSocket (no 1006/404) for at least 30 seconds of idle time.

If all four checks pass, the original notebook should now run without kernel restarts. Re‑open the problematic notebook and execute a representative cell to confirm.

Limitations

This guide assumes a single‑user Jupyter Notebook installation (classic or JupyterLab) on Linux/macOS/Windows with direct filesystem access. Multi‑user deployments (JupyterHub, Kubernetes) add authentication, spawner, and resource‑quota layers that can produce similar symptoms but require additional diagnostics not covered here.