DataSpell Jupyter Kernel Disconnects and Timeouts: A Diagnostic Guide

The recognizable condition

In DataSpell a notebook cell shows "Kernel disconnected" or cells hang with "Execution timeout". The notebook UI remains responsive but the kernel status indicator is red or spinning, and the Event Log or Notifications tool window reports socket or connection errors. The useful takeaway is that most failures are configuration mismatches or resource contention, not a broken notebook file.

Cause and diagnostic signals

Ordered checks

1. Confirm interpreter consistency

Open the notebook and run a cell with import sys; print(sys.executable). Compare the printed path with the interpreter shown in Settings > Project: > Python Interpreter and with the interpreter configured for the Jupyter server in DataSpell. A mismatch means the kernel is launching from a different environment than the project expects.

Fix: Set the same interpreter for the project and for the Jupyter server. In DataSpell, open the notebook context menu > Change Interpreter, then restart the kernel. Rollback is to reselect the previous interpreter from the interpreter list.

2. Verify Jupyter server reachability

Check the Jupyter server URL in DataSpell under Tools > Jupyter > Jupyter Servers. Note the host and port. Test connectivity by attempting to open the server URL directly in a web browser from the same machine. If the browser cannot connect, the server is not reachable.

Fix for local server: ensure the port is not blocked by OS firewall. For remote server, confirm SSH tunnel or VPN is active and stable. Changing the Jupyter server URL to a remote instance requires consistent network connectivity; interruption will cause disconnects.

3. Look for zombie kernel processes

Open the Event Log or Notifications tool window in DataSpell for socket connection errors indicating address already in use. On the host OS, list processes that may hold Jupyter ports. Run in a terminal with user permissions: ps aux | grep jupyter on macOS/Linux or Task Manager on Windows.

Fix: Stop kernels from DataSpell via the Jupyter tool window, then terminate lingering processes. Manually killing PID processes may lead to data loss if the kernel had unsaved state in memory. After cleanup, restart the kernel from DataSpell.

4. Check IDE memory pressure

Large dataframe previews can increase JVM memory use. Open Help > Change Memory Settings and note the current heap allocation. Monitor system memory usage while reproducing the timeout.

Fix: Increase JVM heap within safe limits. Increasing JVM heap size excessively may starve the OS of memory, causing system-wide swap thrashing. A practical way to check the result is to reopen a previously problematic notebook and render the same dataframe without IDE freezes.

5. Validate environment activation

When using Conda or virtual environments, confirm the activation method matches the interpreter. In the notebook, run import sys; print(sys.prefix) and compare with the environment path.

Fix: Recreate the Jupyter kernel spec for the correct environment via the Python Interpreter settings. Ensure packages are installed in the selected environment, not only globally.

Escalation criteria

• Disconnects persist after interpreter alignment, server reachability confirmed, and zombie processes cleared.
• Timeouts occur with small cells and low memory usage, suggesting DataSpell or Jupyter server version incompatibility.
• Event Log shows repeated socket errors with no clear port conflict.

In these cases collect the DataSpell log files, the Jupyter server logs, and the exact interpreter and server configuration, then escalate to JetBrains support with reproduction steps.

Limitations

This guide covers well-established configuration issues. Behavior can vary with OS, DataSpell build, and remote server setup. Verification steps are required on your environment; do not assume a fix applies without confirming the diagnostic signal first.