jlcodes99/cockpit-tools · error · std::io::Error

NotFound

NotFound

Error message

指定终端未找到

What it means

In `src-tauri/src/commands/codex_instance.rs` (around line 4037), the Linux terminal spawn chain for launching a Codex instance hits the gnome-terminal fallback branch; when the request is for a specific terminal (`use_system_terminal == false`) and the earlier spawn failed, the branch returns `Err(ErrorKind::NotFound, "指定终端未找到")`. It indicates the explicitly selected terminal emulator could not be spawned.

Source

Thrown at src-tauri/src/commands/codex_instance.rs:4037

            .map_err(|e| format!("打开终端失败 ({}): {}", plan.terminal_name, e))?;
        drop(child);
        return Ok(format!("已在 {} 执行 Codex CLI 命令", plan.terminal_name));
    }

    #[cfg(target_os = "linux")]
    {
        let shell_command = format!("{}; exec bash", command);
        let use_system_terminal = terminal.is_empty() || terminal.eq_ignore_ascii_case("system");
        let launch_result = Command::new(&plan.program)
            .args(&plan.args)
            .spawn()
            .or_else(|_| {
                if use_system_terminal {
                    Command::new("gnome-terminal")
                        .args(["--", "bash", "-lc", &shell_command])
                        .spawn()
                } else {
                    Err(std::io::Error::new(
                        std::io::ErrorKind::NotFound,
                        "指定终端未找到",
                    ))
                }
            })
            .or_else(|_| {
                if use_system_terminal {
                    Command::new("konsole")
                        .args(["-e", "bash", "-lc", &shell_command])
                        .spawn()
                } else {
                    Err(std::io::Error::new(
                        std::io::ErrorKind::NotFound,
                        "指定终端未找到",
                    ))
                }
            })
            .or_else(|_| Command::new("sh").args(["-lc", &command]).spawn());

View on GitHub (pinned to 1ed8b77992)

Solutions

  1. Enable "use system terminal" for the instance so the x-terminal-emulator/gnome-terminal/konsole fallbacks apply.
  2. Install the selected terminal emulator or fix its PATH entry.
  3. Update the instance's terminal setting to an installed emulator.
  4. The chain still falls through to further fallbacks and finally `sh -lc`; verify which link actually surfaced the error in the returned message.

Example fix

// before
Err(std::io::Error::new(std::io::ErrorKind::NotFound, "指定终端未找到"))
// after
Err(std::io::Error::new(
    std::io::ErrorKind::NotFound,
    format!("无法启动指定终端（未安装或不在 PATH 中）。请在设置中改用系统终端。"),
))
Defensive patterns

Strategy: validation

Validate before calling

// before spawn: check the requested binary
if !use_system_terminal && which::which(&terminal).is_err() {
    return Err(format!("指定终端未安装: {}", terminal));
}

Type guard

fn is_terminal_not_found(e: &std::io::Error) -> bool {
    e.kind() == std::io::ErrorKind::NotFound && e.to_string().contains("指定终端未找到")
}

Try / catch

match launch_codex_instance(&cfg) {
    Ok(pid) => Ok(pid),
    Err(e) if e.contains("指定终端未找到") => {
        launch_codex_instance(&cfg.with_system_terminal())
    }
    Err(e) => Err(e),
}

Prevention

When it happens

Trigger: Launching a Codex instance CLI with a named terminal on Linux where `Command::new(<terminal>)` fails (binary not installed / not on PATH) and `use_system_terminal` is false, so the gnome-terminal arm short-circuits with NotFound.

Common situations: User picked a terminal in Codex instance settings that is not installed; headless/minimal Linux environments missing GUI terminals; PATH differs between the app's launch context and the user's shell.

Understand the failure class

Background: "Not Found" / HTTP 404 Errors: What They Mean and How to Fix Them Across Libraries — this error's family across 6 libraries.

Related errors

AI-assisted analysis of jlcodes99/cockpit-tools@1ed8b77992 (2026-09-05). Data as JSON: /api/errors/5709832f960ae2f0. Report an issue: GitHub.