{"record":{"id":"aaf09bd846caf9c7","repo":"zeroclaw-labs/zeroclaw","slug":"runtime-shell-shell-was-not-found-on-path-use","errorCode":null,"errorMessage":"runtime.shell {shell:?} was not found on PATH; use an absolute path or install the shell","messagePattern":"runtime\\.shell (.+?) was not found on PATH; use an absolute path or install the shell","errorType":"validation","errorClass":"anyhow::Error","httpStatus":null,"severity":"error","filePath":"crates/zeroclaw-config/src/platform/mod.rs","lineNumber":54,"sourceCode":"\n    if shell.trim().is_empty() {\n        anyhow::bail!(\"runtime.shell must not be empty or whitespace\");\n    }\n\n    let path = std::path::Path::new(shell);\n    let resolved = if path.is_absolute() {\n        path.to_path_buf()\n    } else if path.components().count() > 1 {\n        anyhow::bail!(\n            \"runtime.shell {shell:?} is a relative path; use a bare name resolved on PATH (e.g. \\\"bash\\\") or an absolute path (e.g. \\\"/bin/bash\\\")\"\n        );\n    } else {\n        match std::env::split_paths(&std::env::var_os(\"PATH\").unwrap_or_default())\n            .map(|dir| dir.join(shell))\n            .find(|candidate| candidate.is_file())\n        {\n            Some(found) => found,\n            None => anyhow::bail!(\n                \"runtime.shell {shell:?} was not found on PATH; use an absolute path or install the shell\"\n            ),\n        }\n    };\n\n    if !resolved.exists() {\n        anyhow::bail!(\n            \"runtime.shell {shell:?} (resolved to {}) does not exist\",\n            resolved.display()\n        );\n    }\n\n    let metadata = match resolved.metadata() {\n        Ok(metadata) => metadata,\n        Err(e) => anyhow::bail!(\n            \"runtime.shell {shell:?} (resolved to {}) could not be inspected: {e}\",\n            resolved.display()\n        ),","sourceCodeStart":36,"sourceCodeEnd":72,"githubUrl":"https://github.com/zeroclaw-labs/zeroclaw/blob/88bb9c8533fc57ed7a03e36ca7c9ed2bf8336dcc/crates/zeroclaw-config/src/platform/mod.rs#L36-L72","documentation":"When runtime.shell is a bare name, validate_shell walks PATH and takes the first directory containing a file of that name; if no PATH entry has one it bails. This lookup only checks is_file() — executability of the resolved path is verified by the later checks.","triggerScenarios":"runtime.shell = \"fish\" (or zsh, nu, ...) with no executable of that name in any PATH entry of the zeroclaw process on unix.","commonSituations":"Shell installed under a nonstandard prefix not on PATH; zeroclaw launched from systemd, docker, or a GUI launcher with a minimal PATH; the shell simply not installed on the machine.","solutions":["Use the absolute path where the shell actually lives (e.g. /opt/homebrew/bin/fish).","Install the shell (apt install fish / brew install fish).","Fix the PATH seen by the process: systemd Environment=PATH=..., docker ENV, or launch from a login shell.","Fall back to a shell that is essentially always present: /bin/sh or /bin/bash."],"exampleFix":"# before\n[runtime]\nshell = \"fish\"   # not on PATH\n\n# after\n[runtime]\nshell = \"/opt/homebrew/bin/fish\"","handlingStrategy":"validation","validationCode":"fn on_path(name: &str) -> Option<std::path::PathBuf> {\n    std::env::split_paths(&std::env::var_os(\"PATH\").unwrap_or_default())\n        .map(|dir| dir.join(name))\n        .find(|c| c.is_file())\n}\n\nif shell == bare_name && on_path(shell).is_none() { /* use an absolute path instead */ }","typeGuard":null,"tryCatchPattern":"match create_runtime(&config) {\n    Err(e) if e.to_string().contains(\"not found on PATH\") => {\n        // pin an absolute path (or install the shell / fix PATH) and retry\n    }\n    other => other,\n}","preventionTips":["Prefer absolute paths for shells in configs that run on multiple machines.","Check the PATH of service/launcher contexts (systemd, docker, .desktop) — they are usually minimal.","Fall back to /bin/sh or /bin/bash for portable configs."],"tags":["runtime","shell","path","environment"],"backgroundTag":"shell-not-found-on-path","analyzedSha":"88bb9c8533fc57ed7a03e36ca7c9ed2bf8336dcc","analyzedAt":"2026-08-23T01:07:41.857Z","schemaVersion":2},"datasetVersion":"2026-08-23T08:06:27.607Z"}