gitbutlerapp/gitbutler · error

Unknown terminal

Error message

Unknown terminal: {terminal_id}

What it means

On macOS, open_in_terminal() matches terminal_id against a known list of terminals; the fall-through arm bails with 'Unknown terminal' for any unrecognized identifier. The terminal id comes from caller settings and must be one the library knows how to launch.

Solutions

1. Use a supported terminal id for macOS (e.g. iterm, terminal, warp, alacritty, kitty, wezterm, hyper)
2. Check Settings and pick a terminal from the supported list
3. Upgrade to a build that supports the desired terminal

Example fix

// before
open_in_terminal("konsole", path) // on macOS
// after
open_in_terminal("iterm", path)

const MACOS_TERMINALS: [&str; 7] = ["terminal","iterm","warp","alacritty","kitty","wezterm","hyper"];
fn is_known_macos_terminal(id: &str) -> bool { MACOS_TERMINALS.contains(&id) }

fn is_supported_terminal(id: &str) -> bool { MACOS_TERMINALS.contains(&id) }

When it happens

Trigger: Calling open_in_terminal on macOS with a terminal_id string not in the macOS match list (typo, custom id, or a terminal supported only on Linux/Windows).

Common situations: Settings synced across platforms carrying a Linux-only terminal id to macOS, user-edited settings with a misspelled terminal name, or a newly added terminal not yet in this build.

Understand the failure class

Background: Invalid enum value errors: "Unknown type", "Invalid scope", "must be one of" — when a string is not on the library's allowed list — this error's family across 23 libraries.

Related errors

• DefaultTerminalNotFound
• A 'but' binary already exists at
• CLI installation failed
• CliInstallCancelled
• Could not find application for

AI-assisted analysis of gitbutlerapp/gitbutler@58e5313667 (2026-09-18). Data as JSON: /api/errors/103812cd4f507cdb. Report an issue: GitHub.

Appendix: source

Thrown at crates/but-api/src/open/mod.rs:472

                    .arg("--args")
                    .arg("--working-directory")
                    .arg(&path);
                run_terminal_command(cmd, "Alacritty", &path)?;
            }
            "kitty" => open_with_path("kitty", Some("Kitty"))?,
            // WezTerm does not support `open -a WezTerm <path>`. Their docs state you have to use their CLI.
            // https://wezterm.org/config/launch.html#specifying-the-current-working-directory
            "wezterm-mac" => {
                let cli_found = which::which("wezterm").is_ok();
                if !cli_found {
                    return Err(anyhow::anyhow!("'wezterm' CLI was not found on PATH.")
                        .context(but_error::Code::DefaultTerminalNotFound));
                }
                let mut cmd = Command::new("wezterm");
                cmd.arg("start").arg("--cwd").arg(&path);
                run_terminal_command(cmd, "WezTerm", &path)?;
            }
            _ => bail!("Unknown terminal: {terminal_id}"),
        };
    } else if cfg!(target_os = "linux") {
        let binary = terminal::terminal_binary(&terminal_id);

        // Check if the terminal binary exists in PATH before attempting to launch.
        // This lets us give a clear error directing users to Settings, rather than
        // a vague launch failure (which could be confused with path issues).
        let binary_found = which::which(binary).is_ok();
        if !binary_found {
            return Err(anyhow::anyhow!(
                "'{binary}' was not found. Make sure it is installed and available on your PATH."
            )
            .context(but_error::Code::DefaultTerminalNotFound));
        }

        match terminal_id.as_str() {
            // Terminals that inherit parent process CWD (no explicit flags needed).
            // Note: `binary` is used instead of the terminal ID because some terminals

View on GitHub (pinned to 58e5313667)