{"record":{"id":"2bed226d03b3eaeb","repo":"gitbutlerapp/gitbutler","slug":"defaultterminalnotfound","errorCode":"DefaultTerminalNotFound","errorMessage":"'{app_name}' was not found - `open -Ra {app_name}` failed.","messagePattern":"'(.+?)' was not found - `open -Ra (.+?)` failed\\.","errorType":"exception","errorClass":"but_error::Code","httpStatus":null,"severity":"error","filePath":"crates/but-api/src/open/mod.rs","lineNumber":408,"sourceCode":"                .map_or(\"unknown\".to_string(), |c| c.to_string());\n            if stderr.is_empty() {\n                bail!(\"{terminal_name} exited with non-zero status: {status_code}\",);\n            } else {\n                bail!(\"Failed to open {terminal_name} ({status_code}): {stderr}\");\n            }\n        }\n\n        /// Check if a macOS application is installed using `open -Ra`.\n        fn ensure_app_installed(app_name: &str) -> Result<()> {\n            let status = Command::new(\"open\")\n                .arg(\"-Ra\")\n                .arg(app_name)\n                .stdout(Stdio::null())\n                .stderr(Stdio::null())\n                .status()\n                .context(\"Failed to run 'open -Ra' to check application availability\")?;\n            if !status.success() {\n                return Err(anyhow::anyhow!(\n                    \"'{app_name}' was not found - `open -Ra {app_name}` failed.\"\n                )\n                .context(but_error::Code::DefaultTerminalNotFound));\n            }\n            Ok(())\n        }\n\n        let open_with_path = |app_name: &str, alt_app_name: Option<&str>| {\n            ensure_app_installed(app_name)?;\n            let mut cmd = Command::new(\"open\");\n            cmd.arg(\"-a\").arg(app_name).arg(&path);\n            run_terminal_command(cmd, alt_app_name.unwrap_or(app_name), &path)\n        };\n\n        match terminal_id.as_str() {\n            // These terminals support `open -a <app> <path>` as folder handlers\n            \"terminal\" => open_with_path(\"Terminal\", None)?,\n            \"iterm2\" => open_with_path(\"iTerm\", Some(\"iTerm2\"))?,","sourceCodeStart":390,"sourceCodeEnd":426,"githubUrl":"https://github.com/gitbutlerapp/gitbutler/blob/2497b8007aa4a1922dae9a805b32ffe5b5037785/crates/but-api/src/open/mod.rs#L390-L426","documentation":"On macOS, launching a configured terminal first verifies the app bundle exists by running open -Ra <AppName>; a non-zero exit means the app is not installed under that name. The error carries Code::DefaultTerminalNotFound so the UI can route to a settings/installation prompt.","triggerScenarios":"The user selected a terminal (Kitty, WezTerm, Alacritty, iTerm...) whose app bundle is not installed, was installed under a different name, or was uninstalled after the setting was saved.","commonSituations":"Settings referencing an app the user removed; installing only a CLI (brew install kitty) without the application bundle; renamed app bundles after updates.","solutions":["Install the app bundle (brew install --cask kitty / wezterm / alacritty / iterm2)","Switch the terminal selection in Settings to one that is installed","Clear the stale terminal preference so the default is used"],"exampleFix":"# before: settings select 'Kitty' but only the CLI is installed\nbrew install kitty        # CLI only; `open -Ra Kitty` still fails\n\n# after: install the app bundle\nbrew install --cask kitty","handlingStrategy":"validation","validationCode":"fn app_installed(app: &str) -> bool {\n    std::process::Command::new(\"open\")\n        .args([\"-Ra\", app])\n        .stdout(std::process::Stdio::null())\n        .stderr(std::process::Stdio::null())\n        .status()\n        .map(|s| s.success())\n        .unwrap_or(false)\n}\n\nif !app_installed(&configured_terminal) {\n    // fall back to Terminal.app or prompt the user before opening\n}","typeGuard":"use but_error::{AnyhowContextExt, Code};\n\nfn is_default_terminal_not_found(err: &anyhow::Error) -> bool {\n    err.custom_context().is_some_and(|c| c.code == Code::DefaultTerminalNotFound)\n}","tryCatchPattern":"match open_terminal(ctx, path).await {\n    Err(err) if is_default_terminal_not_found(&err) => {\n        // open settings / suggest installing the selected terminal app\n    }\n    other => other,\n}","preventionTips":["Verify the terminal app is installed (open -Ra) at selection time in settings","Clear the terminal setting when its app is uninstalled","Use the DefaultTerminalNotFound code to route to a settings prompt, not a generic error"],"tags":["macos","terminal","app-not-found","settings","open"],"backgroundTag":"application-not-installed","analyzedSha":"2497b8007aa4a1922dae9a805b32ffe5b5037785","analyzedAt":"2026-08-17T00:30:25.648Z","schemaVersion":2},"datasetVersion":"2026-08-17T04:17:16.089Z"}