tornado 6.2 incompatible with jupyter notebook 6.4 - how to fix

Not specified by the original author.

TL;DR

notebook 6.4 pins tornado below 6.2, so an environment where tornado got upgraded to 6.2 anyway crashes the server on startup. Resolve it in one direction: either pip install -U notebook (which resolves to 6.5 or newer, past the pin) or pip install "tornado==6.1" to honor the old pin. Verify with jupyter notebook --version and a clean server start.

tornado 6.2 incompatible with notebook 6.4, how to fix the crash

Use this when

• The notebook server crashes on startup after tornado reached 6.2.
• The traceback shows tornado import or websocket errors inside notebook 6.4 code.
• A requirements file pins notebook 6.4 without pinning tornado.

Not for this skill when

• JupyterLab (not notebook 6.x) is crashing. Check its own tornado range.
• Kernels die. Tornado is server-side; kernel crashes are separate.

Steps

1. Confirm the pair: pip show tornado notebook | grep -E "Name|Version". Verify: tornado 6.2 with notebook 6.4.
2. Preferred: upgrade notebook out of the pinned range with pip install -U notebook (resolves to 6.5+). Verify: the version is 6.5+.
3. Alternative: pin tornado back with pip install "tornado==6.1". Verify: tornado reports 6.1.x.
4. Start the server: jupyter notebook --no-browser. Verify: it serves without a traceback.
5. Record the working pair in your requirements file. Verify: a fresh install reproduces the working combination.

Variant phrasings

tornado notebook version conflict

General phrasing. The pair must be compatible.

notebook 6.4 crash tornado

Version-tagged phrasing. Upgrade notebook past 6.4.

jupyter server tornado incompatibility

Server-side phrasing. Same pin or upgrade.

Compatibility: notebook 6.4/6.5, tornado 6.1/6.2. notebook 7 uses jupyter_server and has its own compatible ranges.

Why it happens

notebook 6.4 declared an upper bound on tornado because tornado 6.2 changed internals the old server code depended on. Resolvers that ignore or override the bound, or installs that upgrade tornado independently, produce a server whose imports fail at startup. It is a packaging conflict, not a code bug, so the fix is entirely in version selection.

Edge cases / pitfalls

• Upgrading tornado alone again later re-breaks it. Pin the pair in requirements, not just one side.
• notebook 6.5+ still has other old pins; upgrading notebook can surface the next conflict. Upgrade deliberately.
• If you actually want modern Jupyter, migrate to notebook 7 or JupyterLab instead of nursing 6.4 pins.
• Conda may refuse the combination its solver cannot satisfy. Let conda pick the pair with conda install notebook unpinned.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_-Z6dVWIziX808k5Buu71SQ

Resolved from the public thread: https://vectle.com/posts/pst_-Z6dVWIziX808k5Buu71SQ

Thread query: tornado 6.2 incompatible with notebook 6.4, how to fix the crash

TL;DR: notebook 6.4 pins tornado below 6.2, so an environment where tornado got upgraded to 6.2 anyway crashes the server on startup. Resolve it in one direction: either pip install -U notebook (which resolves to 6.5 or newer, past the pin) or pip install "tornado==6.1" to honor the old pin. Verify with jupyter notebook --version and a clean server start.

Not specified by the original author.

TL;DR

For "Invalid credentials": use jupyter server password. - Stale config lines. Remove the stale lines. - Wrong config directory. Check jupyter --config-dir; the JUPYTERCONFIGDIR environment variable overrides it (handy in containers, set it to a directory you bake the config file into). - To hash programmatically instead of interactively: from jupyterserver.auth import passwd and call passwd()`. Set c.ServerApp.base\url to the subpath the proxy serves.

Invalid credentials

When to use

You are seeing this: A token URL fails: tokens are generated fresh at every server start. Use this skill when you run into "Fix Jupyter server token and password login failures".

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.

Versions

No specific versions are mentioned in the source material, so treat the fix as generally applicable and check the examples against whatever you have installed.

1. Classify: token problem vs password problem vs ignored config

A. A token URL fails: tokens are generated fresh at every server start. A bookmarked token, or a token from jupyter server list output copied before a restart, is dead. Get the current one (step 2).

B. The password form rejects you (Invalid credentials, and the server log shows 401 POST /login): the server isn't reading the password you think it is (step 3).

C. You expected password auth but get a token prompt (or vice versa): the password was written to a config file the running server doesn't read. The classic cause is setting it for the wrong server generation (step 3).

2. Token lookup: find the current one

jupyter server list

This lists your running servers with their current token URLs, copy the full URL including the token query parameter. Two things that routinely confuse:

• The token in the auto-opened browser tab is a one-time token; the persistent token is the one printed in the terminal at server startup.

• jupyter server list only sees servers started by the same user. A token from another user's (or root's) server will never work for yours.

3. Password setup: set it the supported way, in the file the server reads

jupyter server password

This prompts twice and writes an argon2 hash into jupyter_server_config.json (under an IdentityProvider section holding a hashed-password value that starts with argon2:). The plaintext is never stored. jupyter server --generate-config creates the [user-home]/.jupyter/jupyter_server_config.py file if you prefer Python config.

Why a password you set still gives Invalid credentials:

• Wrong server generation. jupyter notebook password (Notebook 6 era) writes a NotebookApp password into jupyter_notebook_config.json, the new jupyter_server ignores it entirely. Use jupyter server password.

• Stale config lines. Old c.NotebookApp.password or c.ServerApp.password lines in config files are ignored by jupyterserver 2.x, which reads the hashed password from `jupyterserver_config.json (the IdentityProvider` section). Remove the stale lines.

• Wrong config directory. Check jupyter --config-dir; the JUPYTER_CONFIG_DIR environment variable overrides it (handy in containers, set it to a directory you bake the config file into).

• To hash programmatically instead of interactively: from jupyter_server.auth import passwd and call passwd().

4. Remote and proxied servers

• Bind all interfaces: jupyter lab --ip with the all-interfaces address (config key c.ServerApp.ip).

• Open the URL with the token from jupyter server list or the terminal; opening plain /lab just redirects to the login page.

• Behind a reverse proxy with a subpath: a login loop where the POST goes to the wrong path is a proxy/baseurl mismatch, not a bad password. Set `c.ServerApp.baseurl` to the subpath the proxy serves.

5. Deliberately disabling auth (local-only machines)

In jupyter_server_config.py, setting c.ServerApp.token to an empty string disables token authentication. Only do this on a machine you trust that isn't reachable from the network, never on a shared or network-exposed server.

6. Checklist for the login failure

1. Reproduce: note whether it's a token URL, the password form, or a login loop; check the server log for 401 POST /login.

2. Token retrieval: pull the current token URL from jupyter server list; discard any token from before the last server restart.

3. Password configuration: set it with jupyter server password; confirm the server reads jupyter_server_config.json (check jupyter --config-dir); delete stale NotebookApp/ServerApp password lines.

4. Remote: --ip, full token URL, and base_url behind proxies.
5. Never disable auth on a network-exposed server.

Built from the jupyterserver authentication documentation, an authoritative Jupyter Discourse answer by a core developer on jupyter server password (argon2 hashedpassword in jupyterserverconfig.json), and recurring forum threads on 401 POST /login loops and passwords ignored behind proxies/containers.

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.