{"record":{"id":"f18f63b905c4d38a","repo":"github/copilot-sdk","slug":"failed-to-start-cli-server-w","errorCode":null,"errorMessage":"failed to start CLI server: %w","messagePattern":"failed to start CLI server: %w","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"critical","filePath":"go/client.go","lineNumber":2182,"sourceCode":"\t\t}\n\t}\n\n\tif c.useStdio {\n\t\t// For stdio mode, we need stdin/stdout pipes\n\t\tstdin, err := c.process.StdinPipe()\n\t\tif err != nil {\n\t\t\treturn fmt.Errorf(\"failed to create stdin pipe: %w\", err)\n\t\t}\n\n\t\tstdout, err := c.process.StdoutPipe()\n\t\tif err != nil {\n\t\t\treturn fmt.Errorf(\"failed to create stdout pipe: %w\", err)\n\t\t}\n\n\t\tc.process.Stderr = truncbuffer.NewTruncBuffer(stderrBufferSize)\n\n\t\tif err := c.process.Start(); err != nil {\n\t\t\treturn fmt.Errorf(\"failed to start CLI server: %w\", err)\n\t\t}\n\n\t\tc.monitorProcess()\n\n\t\t// Create JSON-RPC client immediately\n\t\tc.client = jsonrpc2.NewClient(stdin, stdout)\n\t\tc.client.SetProcessDone(c.processDone, c.processErrorPtr)\n\t\tc.client.SetOnClose(c.handleConnectionClose)\n\t\tc.RPC = rpc.NewServerRPC(c.client)\n\t\tc.internalRPC = rpc.NewInternalServerRPC(c.client)\n\t\tc.setupNotificationHandler()\n\t\tc.client.Start()\n\n\t\treturn nil\n\t} else {\n\t\t// For TCP mode, capture stdout to get port number\n\t\tstdout, err := c.process.StdoutPipe()\n\t\tif err != nil {","sourceCodeStart":2164,"sourceCodeEnd":2200,"githubUrl":"https://github.com/github/copilot-sdk/blob/cd8cf15dc3f9e762615790aaed0a771a0f392755/go/client.go#L2164-L2200","documentation":"Connect wraps the error from process.Start() with this message when the CLI subprocess cannot be launched in stdio mode. The JSON-RPC session is never established. Typical causes are a missing/non-executable binary, bad working directory, or exec failures.","triggerScenarios":"Connect() with useStdio enabled and os/exec Start() fails: CLI binary path not found, binary lacks execute permission, invalid working directory, or exec format error.","commonSituations":"CLI not installed or not on PATH, wrong WithCommand/args configuration, running on an unsupported platform/architecture, or restricted container images without the binary.","solutions":["Verify the CLI binary path is correct and the binary exists and is executable (which <cli>, chmod +x).","Install the required CLI (e.g. npm install -g @anthropic-ai/claude-code) or point the SDK at the right path.","Check the wrapped error: 'no such file or directory' means bad path; 'permission denied' means missing exec bit.","Ensure the working directory passed to the command exists and the binary matches the OS/architecture."],"exampleFix":"// before\nclient, _ := NewClient(WithCommand(\"claude-x\")) // typo, not installed\nclient.Connect(ctx) // failed to start CLI server: exec: \"claude-x\": executable file not found\n\n// after\nclient, _ := NewClient(WithCommand(\"claude\"))\nif err := client.Connect(ctx); err != nil {\n    return fmt.Errorf(\"connect: %w\", err)\n}","handlingStrategy":"try-catch","validationCode":"path := \"claude\" // or configured command\nif _, err := exec.LookPath(path); err != nil {\n    return fmt.Errorf(\"CLI binary %q not found in PATH: %w\", path, err)\n}","typeGuard":null,"tryCatchPattern":"if err := client.Connect(ctx); err != nil {\n    if strings.Contains(err.Error(), \"failed to start CLI server\") {\n        return fmt.Errorf(\"check CLI install/path: %w\", err)\n    }\n    return err\n}","preventionTips":["Verify the CLI is installed and on PATH before app start.","Run exec.LookPath on the configured command in startup checks.","Confirm exec permissions and correct platform binary.","Pin and document the required CLI version alongside the SDK."],"tags":["go","process","spawn","stdio"],"backgroundTag":"command-not-found","analyzedSha":"cd8cf15dc3f9e762615790aaed0a771a0f392755","analyzedAt":"2026-09-09T18:32:31.973Z","contentChangedAt":"2026-09-09T18:32:31.973Z","schemaVersion":2},"datasetVersion":"2026-09-15T23:17:13.987Z"}