{"record":{"id":"66c45d192bc0d619","repo":"chenhg5/cc-connect","slug":"acp-parse-initialize-result-w","errorCode":null,"errorMessage":"acp: parse initialize result: %w","messagePattern":"acp: parse initialize result: %w","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"agent/acp/session.go","lineNumber":186,"sourceCode":"\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{\n\t\t\t\"methodId\": authMethod,\n\t\t}); err != nil {\n\t\t\treturn fmt.Errorf(\"acp: authenticate (%s): %w\", authMethod, err)\n\t\t}\n\t\tslog.Debug(\"acp: authenticated\", \"method_id\", authMethod)","sourceCodeStart":168,"sourceCodeEnd":204,"githubUrl":"https://github.com/chenhg5/cc-connect/blob/4000b2338aa6e850c99df54f8b0ed6ed7460b401/agent/acp/session.go#L168-L204","documentation":"Wrapped when the JSON-RPC result of `initialize` cannot be unmarshalled into acpInitializeResult. The agent responded to initialize, but its payload does not match the expected schema (agentCapabilities, protocolVersion etc.), so the session cannot determine its capabilities and the handshake aborts.","triggerScenarios":"The agent returned a JSON-RPC result that is not a JSON object (e.g. null, string, or an error-shaped body), or a result missing/differently-typed fields (protocolVersion not a number/string, agentCapabilities not an object) so json.Unmarshal fails.","commonSituations":"Agent implements an older/different ACP dialect whose initialize result diverges from the expected schema; agent returns plain text instead of JSON-RPC; a proxy/wrapper mangles the response; protocol version mismatch causing non-standard fields where typed ones are expected.","solutions":["Log/inspect the raw `res` payload returned by initialize to see the actual shape the agent sent.","Verify the agent implements the ACP initialize result schema (protocolVersion, agentCapabilities.loadSession, agentCapabilities.sessionCapabilities).","Upgrade cc-connect or the agent so both sides agree on the protocol version.","If the agent wraps responses in an extra layer, remove the wrapper or adjust the transport to unwrap before unmarshal."],"exampleFix":"// agent returning legacy shape:\n// {\"ok\": true, \"version\": 2}\n// after: upgrade agent to one returning\n// {\"protocolVersion\": 1, \"agentCapabilities\": {\"loadSession\": true}}","handlingStrategy":"try-catch","validationCode":"// sanity-check agent's initialize output once via a manual JSON-RPC call before embedding\nvar probe map[string]json.RawMessage\nif err := json.Unmarshal(res, &probe); err != nil || probe[\"protocolVersion\"] == nil {\n    return fmt.Errorf(\"agent initialize payload non-conforming\")\n}","typeGuard":null,"tryCatchPattern":"sess, err := agent.StartSession(ctx, id, nil)\nif err != nil && strings.Contains(err.Error(), \"parse initialize result\") {\n    slog.Error(\"agent ACP schema mismatch — check agent version\", \"err\", err)\n    return fmt.Errorf(\"incompatible agent ACP dialect: %w\", err)\n}","preventionTips":["Keep the agent binary and cc-connect versions aligned; check both changelogs on upgrade.","Log the raw initialize response at debug level to diagnose schema drift quickly.","Avoid proxies/shims that rewrite JSON-RPC bodies."],"tags":["acp","handshake","json-unmarshal","schema"],"backgroundTag":"json-unmarshal-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"}