wezterm/wezterm · error

invalid wezterm_ssh_backend value: {}, expected either `ssh2

Error message

invalid wezterm_ssh_backend value: {}, expected either `ssh2` or `libssh`

What it means

The catch-all arm of backend dispatch: the wezterm_ssh_backend value in the SSH domain config matched neither 'ssh2' nor 'libssh' (case-sensitive), so run_impl bails before any connection is attempted. Both arms being compiled in means the value is simply unrecognized.

Source

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

            #[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
            ),
        }
    }

    #[cfg(feature = "libssh-rs")]
    fn run_impl_libssh(&mut self) -> anyhow::Result<()> {
        let hostname = self
            .config
            .get("hostname")
            .ok_or_else(|| anyhow!("hostname not present in config"))?
            .to_string();
        let user = self
            .config
            .get("user")
            .ok_or_else(|| anyhow!("username not present in config"))?
            .to_string();

View on GitHub (pinned to 3ff7522b96)

Solutions

1. Correct the value to exactly 'ssh2' or 'libssh' (lowercase)
2. Remove the key entirely to use the build's default backend
3. Double-check for stray whitespace or capitalization in the Lua string

Example fix

-- before
wezterm_ssh_backend = 'libssh-rs',

-- after
wezterm_ssh_backend = 'libssh',

-- Lua: guard the backend string before building the domain
local function valid_backend(b)
  return b == nil or b == 'ssh2' or b == 'libssh'
end
assert(valid_backend(backend), "wezterm_ssh_backend must be 'ssh2' or 'libssh'")

-- Lua
local function is_valid_ssh_backend(v)
  return type(v) == 'string' and (v == 'ssh2' or v == 'libssh')
end

When it happens

Trigger: Any wezterm_ssh_backend value other than the exact strings 'ssh2' or 'libssh' — typos like 'libssh2', 'SSH2', 'ssh 2', 'libssh-rs', or an accidental non-string Lua value that serializes differently.

Common situations: Hand-written config typos; confusion between the lib name 'libssh-rs' and the accepted value 'libssh'; copy-paste from outdated docs.

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 `ss
• invalid wezterm_ssh_backend value: {}, not compiled with `li
• 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/0e256cc1d36d1d34. Report an issue: GitHub.