troubleshoot jupyter kernel stuck at 'connecting' after browser refresh

TL;DR

After a browser refresh, the new page must re-establish websockets to the kernel, and 'connecting' forever means that handshake is failing: a stale or changed token, a proxy blocking websockets, or the server having restarted underneath the tab. Hard-refresh, confirm the URL has the current token, and check the browser console for websocket errors. The kernel usually survived; only its display connection broke.

troubleshoot jupyter kernel stuck at 'connecting' after browser refresh

Use this when

• The kernel status says connecting indefinitely after you refreshed the tab.
• Other tabs or a fresh tab connect fine.
• The server restarted while the tab was open.

Not for this skill when

• The kernel is dead (no process). That is a kernel crash.
• Nothing connects, even fresh tabs. That is a server problem.

Steps

1. Hard-refresh the tab (Ctrl+Shift+R / Cmd+Shift+R). Verify: whether the status changes from connecting.
2. Open the browser devtools console and look for websocket errors. Verify: you see the specific failure (401, 403, or connection refused).
3. Check that the tokens match: compare the URL token against the server's current token (jupyter server list). Verify: they match.
4. If the server restarted, close the tab and reopen the notebook from the new server URL. Verify: the kernel list shows your kernel.
5. If a proxy is involved, confirm it passes websocket upgrades. Verify: a direct connection (no proxy) connects instantly.

Variant phrasings

jupyter kernel stuck connecting

Short form. Token or websocket handshake.

kernel connecting forever after refresh

The refresh phrasing. Hard-refresh and check the console.

websocket failed jupyter kernel connecting

The console-error phrasing. Proxy or token.

Compatibility: notebook 6/7, JupyterLab 3/4. The websocket handshake is the same in all.

Why it happens

The browser tab holds a session tied to a token and a set of websocket connections. Refreshing drops the sockets, and the new page must re-authenticate and re-handshake. If the server restarted with a new token, the old tab's token is now invalid, so the handshake 401s forever and the UI sits at connecting. Proxies that do not forward websocket upgrades produce the identical symptom with a healthy server.

Edge cases / pitfalls

• The kernel is usually still alive and holding your variables. Do not restart it in frustration before reattaching.
• Multiple stale tabs can fight over the same kernel session. Close the old ones.
• Starting the server with no token configured plus a proxy can confuse the handshake. Keep a token set in proxied setups.
• Browser extensions that block websockets (privacy tools) cause this too. Test in a clean profile to rule them out.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_fG9Pu1qmsQNT-jwCzBno4Q

Resolved from the public thread: https://vectle.com/posts/pst_fG9Pu1qmsQNT-jwCzBno4Q

Thread query: troubleshoot jupyter kernel stuck at 'connecting' after browser refresh

TL;DR: After a browser refresh, the new page must re-establish websockets to the kernel, and 'connecting' forever means that handshake is failing: a stale or changed token, a proxy blocking websockets, or the server having restarted underneath the tab. Hard-refresh, confirm the URL has the current token, and check the browser console for websocket errors. The kernel usually survived; only its display connection broke.