{"record":{"id":"8a0eeaf876007622","repo":"zed-industries/zed","slug":"failed-to-connect","errorCode":null,"errorMessage":"failed to connect: {}","messagePattern":"failed to connect: (.+?)","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"crates/remote/src/transport/ssh.rs","lineNumber":712,"sourceCode":"                _ = master_process.wait_connected().fuse() => {\n                    anyhow::Ok(())\n                }\n            };\n\n            if let Err(e) = result {\n                return Err(e.context(\"Failed to connect to host\"));\n            }\n\n            if master_process.as_mut().try_status()?.is_some() {\n                let mut output = Vec::new();\n                let mut stderr = master_process.as_mut().stderr.take().unwrap();\n                stderr.read_to_end(&mut output).await?;\n\n                let error_message = format!(\n                    \"failed to connect: {}\",\n                    String::from_utf8_lossy(&output).trim()\n                );\n                anyhow::bail!(error_message);\n            }\n\n            let socket = SshSocket::new(connection_options, socket_path).await?;\n            drop(askpass);\n            (socket, Some(master_process))\n        };\n\n        #[cfg(windows)]\n        let (socket, master_process_option) = {\n            let askpass_delegate = askpass::AskPassDelegate::new_with_cancellation(cx, {\n                let delegate = delegate.clone();\n                move |prompt, tx, cancellation, cx| {\n                    delegate.ask_password(prompt, tx, cancellation, cx)\n                }\n            });\n\n            let mut askpass =\n                askpass::AskPassSession::new(cx.background_executor().clone(), askpass_delegate)","sourceCodeStart":694,"sourceCodeEnd":730,"githubUrl":"https://github.com/zed-industries/zed/blob/f4178619acd0d47ea1f76a2025c42962c6d6638c/crates/remote/src/transport/ssh.rs#L694-L730","documentation":"Immediately after the connection race, Zed checks whether the ssh master already terminated (try_status() is Some); if so it drains the process's stderr and reports it verbatim as `failed to connect: <stderr>`. The embedded text is ssh's own error output and pinpoints why the connection dropped.","triggerScenarios":"The Unix master ssh process exits during/right after establishment: host key verification failure, permission denied (publickey/password), connection reset, unsupported KEX/ciphers, or invalid options passed through connection_options additional args.","commonSituations":"REMOTE HOST IDENTIFICATION HAS CHANGED after a server rebuild; agent missing the right key (Permission denied (publickey)); bastions or middleboxes resetting the session; typos in extra ssh arguments configured for the connection.","solutions":["Read the embedded ssh stderr — it names the exact cause (host key, auth, network)","Host key changed after rebuild: `ssh-keygen -R <host>` (or edit known_hosts), then reconnect","Auth: confirm the key is loaded (`ssh-add -l`) and the username is correct","Re-check any additional ssh arguments in the connection options for validity"],"exampleFix":"# before: stderr says 'Host key verification failed.'\nssh-keygen -R host.example.com\n\n# after: reconnect from Zed; handshake completes","handlingStrategy":"try-catch","validationCode":"// Preflight the same options Zed will use:\n// ssh -o BatchMode=yes -o ConnectTimeout=5 <user>@<host> true\n// non-zero exit + stderr predicts this failure before opening Zed's session","typeGuard":null,"tryCatchPattern":"if let Err(e) = connect(&opts, cx).await {\n    if let Some(stderr) = e.to_string().strip_prefix(\"failed to connect: \") {\n        // display ssh's own stderr (host key, auth, network) to the user verbatim\n    }\n    return Err(e);\n}","preventionTips":["Clear changed host keys with ssh-keygen -R after server rebuilds","Keep needed keys loaded in the agent (ssh-add -l before connecting)","Validate extra ssh args in connection options against `ssh -G`"],"tags":["ssh","connection","host-key","auth"],"backgroundTag":"ssh-connection-failed","analyzedSha":"f4178619acd0d47ea1f76a2025c42962c6d6638c","analyzedAt":"2026-08-20T19:29:52.058Z","contentChangedAt":"2026-08-20T19:29:52.058Z","schemaVersion":2},"datasetVersion":"2026-09-14T05:17:10.506Z"}