{"record":{"id":"4448aa606df8b03f","repo":"wezterm/wezterm","slug":"invalid-wezterm-ssh-backend-value-not-compile","errorCode":null,"errorMessage":"invalid wezterm_ssh_backend value: {}, not compiled with `ssh2`","messagePattern":"invalid wezterm_ssh_backend value: (.+?), not compiled with `ssh2`","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"wezterm-ssh/src/sessioninner.rs","lineNumber":88,"sourceCode":"    }\n\n    fn run_impl(&mut self) -> anyhow::Result<()> {\n        let backend = self\n            .config\n            .get(\"wezterm_ssh_backend\")\n            .map(|s| s.as_str())\n            .unwrap_or(\n                #[cfg(feature = \"libssh-rs\")]\n                \"libssh\",\n                #[cfg(not(feature = \"libssh-rs\"))]\n                \"ssh2\",\n            );\n        match backend {\n            #[cfg(feature = \"ssh2\")]\n            \"ssh2\" => self.run_impl_ssh2(),\n\n            #[cfg(not(feature = \"ssh2\"))]\n            \"ssh2\" => anyhow::bail!(\n                \"invalid wezterm_ssh_backend value: {}, not compiled with `ssh2`\",\n                backend\n            ),\n\n            #[cfg(feature = \"libssh-rs\")]\n            \"libssh\" => self.run_impl_libssh(),\n\n            #[cfg(not(feature = \"libssh-rs\"))]\n            \"libssh\" => anyhow::bail!(\n                \"invalid wezterm_ssh_backend value: {}, not compiled with `libssh`\",\n                backend\n            ),\n\n            _ => anyhow::bail!(\n                \"invalid wezterm_ssh_backend value: {}, expected either `ssh2` or `libssh`\",\n                backend\n            ),\n        }","sourceCodeStart":70,"sourceCodeEnd":106,"githubUrl":"https://github.com/wezterm/wezterm/blob/3ff7522b9617ec920f7fbdb22b57e93d42d93ee9/wezterm-ssh/src/sessioninner.rs#L70-L106","documentation":"SessionInner::run_impl reads wezterm_ssh_backend from the SSH domain config and dispatches to run_impl_ssh2. This arm is compiled only when the ssh2 cargo feature is OFF, so setting the backend to 'ssh2' in a binary built without the feature fails immediately with this message. wezterm's default (official) builds ship the libssh-rs backend; ssh2 must be selected at compile time.","triggerScenarios":"A wezterm ssh_domain (or wezterm.configure_ssh) setting wezterm_ssh_backend = 'ssh2' while running a wezterm binary compiled without the ssh2 feature (cargo build without --features ssh2 / a distro package built libssh-only).","commonSituations":"Copying a config snippet that recommends the ssh2 backend to work around a libssh auth bug, on a build that doesn't include it; distro or CI-built wezterm with a reduced feature set.","solutions":["Remove wezterm_ssh_backend from the domain config to use the default libssh backend","Set wezterm_ssh_backend = 'libssh' explicitly","If ssh2 is required, build wezterm from source with the feature enabled (e.g. cargo build --release --features ssh2 per the wezterm-ssh crate features)","Check spelling — any other value falls into the 'expected either ssh2 or libssh' arm"],"exampleFix":"-- before\nconfig.ssh_domains = { { name='h', remote_address='h', user='u', wezterm_ssh_backend = 'ssh2' } }\n\n-- after\nconfig.ssh_domains = { { name='h', remote_address='h', user='u', wezterm_ssh_backend = 'libssh' } }","handlingStrategy":"validation","validationCode":"-- Lua: safest guard is to omit wezterm_ssh_backend unless you\n-- built the binary yourself with the ssh2 feature enabled\nlocal domain = { name='h', remote_address='h', user='u' } -- backend defaults","typeGuard":null,"tryCatchPattern":"Catch SessionEvent::Error; if it matches 'not compiled with `ssh2`', rewrite the domain to the default backend and reconnect.","preventionTips":["Omit wezterm_ssh_backend unless you specifically need a non-default backend","Match the config value to the feature set of the binary you actually distribute"],"tags":["wezterm","ssh","config","build-features"],"backgroundTag":"invalid-config-value","analyzedSha":"3ff7522b9617ec920f7fbdb22b57e93d42d93ee9","analyzedAt":"2026-08-20T04:47:31.434Z","contentChangedAt":"2026-08-20T04:47:31.434Z","schemaVersion":2},"datasetVersion":"2026-09-14T00:17:10.932Z"}