zed-industries/zed · error · anyhow::Error

SSH tunnel failed to establish after {} attempts

Error message

SSH tunnel failed to establish after {} attempts

What it means

Raised in the SSH kernel constructor after retrying the tunnel readiness check max_attempts times (100ms apart): each probe of the forwarded port failed, so the tunnel needed for the kernel's ZeroMQ connection never became available and the kernel cannot start.

Source

Thrown at crates/repl/src/kernels/ssh_kernel.rs:187

                    Err(err) => {
                        if attempt % 10 == 0 {
                            log::debug!(
                                "Waiting for SSH tunnel (attempt {}/{}): {}",
                                attempt + 1,
                                max_attempts,
                                err
                            );
                        }
                        if attempt < max_attempts - 1 {
                            cx.background_executor()
                                .timer(std::time::Duration::from_millis(100))
                                .await;
                        }
                    }
                }
            }
            if !connected {
                anyhow::bail!(
                    "SSH tunnel failed to establish after {} attempts",
                    max_attempts
                );
            }

            let mut local_connection_info = connection_info.clone();
            local_connection_info["shell_port"] = serde_json::json!(local_ports[0]);
            local_connection_info["iopub_port"] = serde_json::json!(local_ports[1]);
            local_connection_info["stdin_port"] = serde_json::json!(local_ports[2]);
            local_connection_info["control_port"] = serde_json::json!(local_ports[3]);
            local_connection_info["hb_port"] = serde_json::json!(local_ports[4]);
            local_connection_info["ip"] = serde_json::json!("127.0.0.1");

            let local_connection_file =
                std::env::temp_dir().join(format!("zed_ssh_kernel_{}.json", kernel_id));
            std::fs::write(
                &local_connection_file,
                serde_json::to_string_pretty(&local_connection_info)?,

View on GitHub (pinned to f4178619ac)

Solutions

1. Verify SSH connectivity to the remote host and that the remote kernel is running
2. Increase the attempt budget or check network latency/firewalls
3. Restart the remote kernel and retry the connection
4. Confirm the forwarded ports are not already in use

When it happens

Trigger: Thrown at crates/repl/src/kernels/ssh_kernel.rs:187 when the library encounters an invalid state.

Common situations: See trigger scenarios.

AI-assisted analysis of zed-industries/zed@f4178619ac (2026-08-20). Data as JSON: /api/errors/438aaced97a6087f. Report an issue: GitHub.