{"record":{"id":"07bd7ca7a647c9b8","repo":"chenhg5/cc-connect","slug":"acp-initialize-w","errorCode":null,"errorMessage":"acp: initialize: %w","messagePattern":"acp: initialize: %w","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"agent/acp/session.go","lineNumber":181,"sourceCode":"// SetLiveMode / PermissionModes can answer correctly.\nfunc (s *acpSession) handshake(resumeSessionID string, authMethod string) error {\n\tinitParams := map[string]any{\n\t\t\"protocolVersion\": 1,\n\t\t\"clientCapabilities\": map[string]any{\n\t\t\t\"fs\": map[string]any{\n\t\t\t\t\"readTextFile\":  false,\n\t\t\t\t\"writeTextFile\": false,\n\t\t\t},\n\t\t\t\"terminal\": false,\n\t\t},\n\t\t\"clientInfo\": map[string]any{\n\t\t\t\"name\":    \"cc-connect\",\n\t\t\t\"version\": \"1.0.0\",\n\t\t},\n\t}\n\tres, err := s.tr.call(s.ctx, \"initialize\", initParams)\n\tif err != nil {\n\t\treturn fmt.Errorf(\"acp: initialize: %w\", err)\n\t}\n\n\tvar initOut acpInitializeResult\n\tif err := json.Unmarshal(res, &initOut); err != nil {\n\t\treturn fmt.Errorf(\"acp: parse initialize result: %w\", err)\n\t}\n\tlistSupported := len(initOut.AgentCapabilities.SessionCapabilities.List) > 0\n\tslog.Debug(\"acp: initialized\",\n\t\t\"protocol\", initOut.ProtocolVersion,\n\t\t\"load_session\", initOut.AgentCapabilities.LoadSession,\n\t\t\"list_sessions\", listSupported,\n\t)\n\tif s.callbacks != nil {\n\t\ts.callbacks.reportListSupported(listSupported)\n\t}\n\n\tif strings.TrimSpace(authMethod) != \"\" {\n\t\tif _, err := s.tr.call(s.ctx, \"authenticate\", map[string]any{","sourceCodeStart":163,"sourceCodeEnd":199,"githubUrl":"https://github.com/chenhg5/cc-connect/blob/4000b2338aa6e850c99df54f8b0ed6ed7460b401/agent/acp/session.go#L163-L199","documentation":"Wrapped during the ACP handshake when the JSON-RPC `initialize` request to the agent process fails (transport error, process crash, timeout, or JSON-RPC error response). newACPSession calls handshake and aborts the session (closing the agent process) if initialize cannot complete. The wrapped error carries the underlying cause.","triggerScenarios":"The agent binary crashed before answering initialize, the agent returned a JSON-RPC error for `initialize`, the s.ctx was cancelled (timeout/deadline) while waiting for the response, or the agent emitted a malformed/empty reply to the initialize request.","commonSituations":"Wrong `command` path in config so a non-ACP binary starts; agent version that does not speak the ACP protocol; agent needs an API key and exits immediately at startup; slow agent startup exceeding the call timeout; agent stderr-fatal on missing env vars.","solutions":["Check the agent process actually started and is an ACP server: run the configured command manually and confirm it responds to an ACP initialize request.","Inspect agent stderr — the process-exit path logs stderr via slog.Error; a missing API key or bad flag usually appears there.","Verify the agent version supports ACP protocol version 1 and upgrade/downgrade the agent binary accordingly.","Increase the handshake timeout / check that s.ctx is not cancelled early.","Confirm auth prerequisites (login state, env vars) so the agent does not abort during startup."],"exampleFix":"// config: wrong command silently fails initialize\ncommand = \"/usr/local/bin/agent-cli\"\n// after: point at the real ACP-capable binary\ncommand = \"/usr/local/bin/agent-cli-acp\"","handlingStrategy":"try-catch","validationCode":"cmd := exec.Command(cfg.Command, cfg.Args...)\nif err := cmd.Start(); err != nil { return err }\n// optionally probe: send a minimal ACP initialize with a short timeout before full StartSession","typeGuard":"func isHandshakeErr(err error) bool {\n    return err != nil && strings.HasPrefix(err.Error(), \"acp: initialize: \")\n}","tryCatchPattern":"sess, err := agent.StartSession(ctx, id, nil)\nif err != nil {\n    var pe *exec.ExitError\n    if errors.As(err, &pe) || isHandshakeErr(err) {\n        slog.Error(\"acp agent failed handshake\", \"err\", err)\n        // fall back to another agent or surface config guidance\n    }\n    return err\n}","preventionTips":["Pin a known-good agent binary version in config and verify it with the agent's own version/doctor command.","Smoke-test the configured command manually before deploying.","Ensure required API keys/env vars for the agent are set in the service environment.","Give the handshake a generous timeout for slow-starting agents."],"tags":["acp","handshake","json-rpc","agent-process"],"backgroundTag":"handshake-failed","analyzedSha":"4000b2338aa6e850c99df54f8b0ed6ed7460b401","analyzedAt":"2026-09-06T11:45:09.575Z","contentChangedAt":"2026-09-06T11:45:09.575Z","schemaVersion":2},"datasetVersion":"2026-09-14T05:17:10.506Z"}