chenhg5/cc-connect · error

acp: initialize: %w

Error message

acp: initialize: %w

What it means

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.

Source

Thrown at agent/acp/session.go:181

// SetLiveMode / PermissionModes can answer correctly.
func (s *acpSession) handshake(resumeSessionID string, authMethod string) error {
	initParams := map[string]any{
		"protocolVersion": 1,
		"clientCapabilities": map[string]any{
			"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{

View on GitHub (pinned to 4000b2338a)

Solutions

1. 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.
2. Inspect agent stderr — the process-exit path logs stderr via slog.Error; a missing API key or bad flag usually appears there.
3. Verify the agent version supports ACP protocol version 1 and upgrade/downgrade the agent binary accordingly.
4. Increase the handshake timeout / check that s.ctx is not cancelled early.
5. Confirm auth prerequisites (login state, env vars) so the agent does not abort during startup.

Example fix

// config: wrong command silently fails initialize
command = "/usr/local/bin/agent-cli"
// after: point at the real ACP-capable binary
command = "/usr/local/bin/agent-cli-acp"

cmd := exec.Command(cfg.Command, cfg.Args...)
if err := cmd.Start(); err != nil { return err }
// optionally probe: send a minimal ACP initialize with a short timeout before full StartSession

func isHandshakeErr(err error) bool {
    return err != nil && strings.HasPrefix(err.Error(), "acp: initialize: ")
}

sess, err := agent.StartSession(ctx, id, nil)
if err != nil {
    var pe *exec.ExitError
    if errors.As(err, &pe) || isHandshakeErr(err) {
        slog.Error("acp agent failed handshake", "err", err)
        // fall back to another agent or surface config guidance
    }
    return err
}

When it happens

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

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

Related errors

• acp: authenticate (%s): %w
• acp: session/new: %w
• acp: session/prompt: %w
• acp: parse initialize result: %w
• acp: parse session/new: %w

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