chenhg5/cc-connect · error

acp: parse initialize result: %w

Error message

acp: parse initialize result: %w

What it means

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.

Source

Thrown at agent/acp/session.go:186

			"fs": map[string]any{
				"readTextFile":  false,
				"writeTextFile": false,
			},
			"terminal": false,
		},
		"clientInfo": map[string]any{
			"name":    "cc-connect",
			"version": "1.0.0",
		},
	}
	res, err := s.tr.call(s.ctx, "initialize", initParams)
	if err != nil {
		return fmt.Errorf("acp: initialize: %w", err)
	}

	var initOut acpInitializeResult
	if err := json.Unmarshal(res, &initOut); err != nil {
		return fmt.Errorf("acp: parse initialize result: %w", err)
	}
	listSupported := len(initOut.AgentCapabilities.SessionCapabilities.List) > 0
	slog.Debug("acp: initialized",
		"protocol", initOut.ProtocolVersion,
		"load_session", initOut.AgentCapabilities.LoadSession,
		"list_sessions", listSupported,
	)
	if s.callbacks != nil {
		s.callbacks.reportListSupported(listSupported)
	}

	if strings.TrimSpace(authMethod) != "" {
		if _, err := s.tr.call(s.ctx, "authenticate", map[string]any{
			"methodId": authMethod,
		}); err != nil {
			return fmt.Errorf("acp: authenticate (%s): %w", authMethod, err)
		}
		slog.Debug("acp: authenticated", "method_id", authMethod)

View on GitHub (pinned to 4000b2338a)

Solutions

1. Log/inspect the raw `res` payload returned by initialize to see the actual shape the agent sent.
2. Verify the agent implements the ACP initialize result schema (protocolVersion, agentCapabilities.loadSession, agentCapabilities.sessionCapabilities).
3. Upgrade cc-connect or the agent so both sides agree on the protocol version.
4. If the agent wraps responses in an extra layer, remove the wrapper or adjust the transport to unwrap before unmarshal.

Example fix

// agent returning legacy shape:
// {"ok": true, "version": 2}
// after: upgrade agent to one returning
// {"protocolVersion": 1, "agentCapabilities": {"loadSession": true}}

// sanity-check agent's initialize output once via a manual JSON-RPC call before embedding
var probe map[string]json.RawMessage
if err := json.Unmarshal(res, &probe); err != nil || probe["protocolVersion"] == nil {
    return fmt.Errorf("agent initialize payload non-conforming")
}

sess, err := agent.StartSession(ctx, id, nil)
if err != nil && strings.Contains(err.Error(), "parse initialize result") {
    slog.Error("agent ACP schema mismatch — check agent version", "err", err)
    return fmt.Errorf("incompatible agent ACP dialect: %w", err)
}

When it happens

Trigger: 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.

Common situations: 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.

Understand the failure class

Background: "failed to unmarshal" / json.Unmarshal errors: why parsing a response into a Go struct fails and how to fix it — this error's family across 23 libraries.

Related errors

• acp: parse session/new: %w
• acp: initialize: %w
• acp: authenticate (%s): %w
• acp: session/new: %w
• acp: session/new: empty sessionId

AI-assisted analysis of chenhg5/cc-connect@4000b2338a (2026-09-06). Data as JSON: /api/errors/66c45d192bc0d619. Report an issue: GitHub.