wezterm/wezterm · error

invalid wezterm_ssh_backend value: {}, not compiled with `ss

Error message

invalid wezterm_ssh_backend value: {}, not compiled with `ssh2`

What it means

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.

Source

Thrown at wezterm-ssh/src/sessioninner.rs:88

    }

    fn run_impl(&mut self) -> anyhow::Result<()> {
        let backend = self
            .config
            .get("wezterm_ssh_backend")
            .map(|s| s.as_str())
            .unwrap_or(
                #[cfg(feature = "libssh-rs")]
                "libssh",
                #[cfg(not(feature = "libssh-rs"))]
                "ssh2",
            );
        match backend {
            #[cfg(feature = "ssh2")]
            "ssh2" => self.run_impl_ssh2(),

            #[cfg(not(feature = "ssh2"))]
            "ssh2" => anyhow::bail!(
                "invalid wezterm_ssh_backend value: {}, not compiled with `ssh2`",
                backend
            ),

            #[cfg(feature = "libssh-rs")]
            "libssh" => self.run_impl_libssh(),

            #[cfg(not(feature = "libssh-rs"))]
            "libssh" => anyhow::bail!(
                "invalid wezterm_ssh_backend value: {}, not compiled with `libssh`",
                backend
            ),

            _ => anyhow::bail!(
                "invalid wezterm_ssh_backend value: {}, expected either `ssh2` or `libssh`",
                backend
            ),
        }

View on GitHub (pinned to 3ff7522b96)

Solutions

1. Remove wezterm_ssh_backend from the domain config to use the default libssh backend
2. Set wezterm_ssh_backend = 'libssh' explicitly
3. 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)
4. Check spelling — any other value falls into the 'expected either ssh2 or libssh' arm

Example fix

-- before
config.ssh_domains = { { name='h', remote_address='h', user='u', wezterm_ssh_backend = 'ssh2' } }

-- after
config.ssh_domains = { { name='h', remote_address='h', user='u', wezterm_ssh_backend = 'libssh' } }

-- Lua: safest guard is to omit wezterm_ssh_backend unless you
-- built the binary yourself with the ssh2 feature enabled
local domain = { name='h', remote_address='h', user='u' } -- backend defaults

Catch SessionEvent::Error; if it matches 'not compiled with `ssh2`', rewrite the domain to the default backend and reconnect.

When it happens

Trigger: 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).

Common situations: 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.

Understand the failure class

Background: "Invalid value" and "allowed values are" config errors: what your library rejected and how to fix it — this error's family across 41 libraries.

Related errors

• invalid wezterm_ssh_backend value: {}, not compiled with `li
• invalid wezterm_ssh_backend value: {}, expected either `ssh2
• hostname not present in config
• username not present in config
• invalid keycode {}: {:#}, {:#}

AI-assisted analysis of wezterm/wezterm@3ff7522b96 (2026-08-20). Data as JSON: /api/errors/4448aa606df8b03f. Report an issue: GitHub.