Skip to content

exec: diagnose connection failures with server health checks - #15

Merged
anish749 merged 1 commit into
mainfrom
improve-connection-error-messages
Mar 31, 2026
Merged

exec: diagnose connection failures with server health checks#15
anish749 merged 1 commit into
mainfrom
improve-connection-error-messages

Conversation

@anish749

Copy link
Copy Markdown
Owner

Problem

When the WebSocket connection to the Jupyter server drops (VPN disconnect, network interruption, proxy timeout, kernel shutdown), the CLI shows a generic "Connection is already closed." error from the websocket library. The caller has no way to tell what actually happened.

Solution

Added a diagnostics module (session/diagnostics.py) that:

  1. Classifies exceptions as connection-related vs code execution errors
  2. For connection errors, performs a follow-up HTTP health check against the Jupyter server (with a 5s timeout) to determine the cause
  3. Returns a specific, actionable error message:
    • Server unreachable → "Check network connectivity and VPN"
    • Kernel gone (404) → "Kernel is no longer running... Create a new session"
    • Kernel still alive → "WebSocket connection lost but kernel is still running... likely a network interruption"
    • Server returning errors → reports the HTTP status code

The Session.execute() exception handler now uses these diagnostics for connection failures, while non-connection errors (e.g. kernel code exceptions) continue to pass through unchanged.

When the WebSocket connection to the Jupyter server drops, the CLI
previously showed a generic "Connection is already closed." error.
Now, connection-related exceptions trigger an HTTP health check against
the server to report whether the server is unreachable, the kernel
has been shut down, or the WebSocket dropped while the kernel is
still running.
@anish749
anish749 merged commit f3ef798 into main Mar 31, 2026
1 check passed
@anish749
anish749 deleted the improve-connection-error-messages branch March 31, 2026 14:11
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant