{"record":{"id":"a21df8d2f31a6cc4","repo":"aaif-goose/goose","slug":"failed-to-start-extension","errorCode":null,"errorMessage":"Failed to start extension: {}","messagePattern":"Failed to start extension: (.+?)","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"crates/goose-cli/src/session/mod.rs","lineNumber":451,"sourceCode":"                    ExtensionConfig::Builtin {\n                        name: extension_name.to_string(),\n                        display_name: None,\n                        timeout: None,\n                        bundled: None,\n                        description: extension_name.to_string(),\n                        available_tools: Vec::new(),\n                    }\n                }\n            })\n            .collect()\n    }\n\n    async fn add_and_persist_extensions(&mut self, configs: Vec<ExtensionConfig>) -> Result<()> {\n        for config in configs {\n            self.agent\n                .add_extension(config, &self.session_id)\n                .await\n                .map_err(|e| anyhow::anyhow!(\"Failed to start extension: {}\", e))?;\n        }\n\n        self.invalidate_completion_cache().await;\n\n        Ok(())\n    }\n\n    pub async fn add_extension(&mut self, extension_command: String) -> Result<()> {\n        let config = Self::parse_stdio_extension(&extension_command)?;\n        self.add_and_persist_extensions(vec![config]).await\n    }\n\n    pub async fn add_streamable_http_extension(&mut self, extension_url: String) -> Result<()> {\n        let config = Self::parse_streamable_http_extension(\n            &extension_url,\n            goose::config::DEFAULT_EXTENSION_TIMEOUT,\n        );\n        self.add_and_persist_extensions(vec![config]).await","sourceCodeStart":433,"sourceCodeEnd":469,"githubUrl":"https://github.com/aaif-goose/goose/blob/3810898a7447ec3299be72e223d3570a7aabf0ab/crates/goose-cli/src/session/mod.rs#L433-L469","documentation":"add_and_persist_extensions forwards each ExtensionConfig to Agent::add_extension, which spawns the stdio MCP server process. Any startup failure — spawn error, immediate exit, or failed MCP handshake — is wrapped as 'Failed to start extension: {e}' with the underlying cause in the message.","triggerScenarios":"goose add-extension / --with-extension with a command not on PATH, not executable, missing its runtime (node/python), or an MCP server that crashes before the initialize handshake completes.","commonSituations":"Wrong interpreter path; node_modules missing after a fresh clone; PATH differing between the user's shell and goose's environment; npx fetch failures offline.","solutions":["Run the extension command by hand in the same shell and confirm it starts and stays up","Install the missing runtime or package dependencies the command needs","Use an absolute path for the command when PATH resolution differs","Re-add the extension with corrected KEY=VALUE env prefixes"],"exampleFix":"# before\n--with-extension my-mcp-server            # not on PATH\n# after\n--with-extension node /home/me/my-mcp-server/build/index.js","handlingStrategy":"validation","validationCode":"use std::process::Command;\n\nfn extension_command_runs(cmd: &str) -> bool {\n    let mut parts = cmd.split_whitespace();\n    match parts.next() {\n        Some(bin) => Command::new(bin).output().is_ok(),\n        None => false,\n    }\n}","typeGuard":null,"tryCatchPattern":"if let Err(e) = session.add_extension(cmd.to_string()).await {\n    if e.to_string().contains(\"Failed to start extension\") {\n        eprintln!(\"extension '{}' failed to start; check PATH and dependencies\", cmd);\n    }\n    return Err(e);\n}","preventionTips":["Test-run the extension command in the same shell before adding it to goose","Prefer absolute paths for extension binaries","Ensure the runtime (node, python, uvx) and dependencies are installed and on PATH"],"tags":["extension","mcp","subprocess","startup"],"backgroundTag":null,"analyzedSha":"3810898a7447ec3299be72e223d3570a7aabf0ab","analyzedAt":"2026-08-16T10:14:26.282Z","schemaVersion":2},"datasetVersion":"2026-08-16T13:17:31.715Z"}