chenhg5/cc-connect · error

acp: initialize

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.

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 ( )
• acp: session/new
• acp: session/prompt
• acp: parse initialize result
• acp: parse session/new

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

Appendix: 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)