chenhg5/cc-connect · error

acp: authenticate (%s): %w

Error message

acp: authenticate (%s): %w

What it means

Wrapped when the JSON-RPC `authenticate` call fails during handshake. Authentication is only attempted when an authMethod id is configured; the agent rejected the method id or the request errored, and the session is closed.

Source

Thrown at agent/acp/session.go:202

	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)
	}

	wantResume := resumeSessionID != "" && resumeSessionID != core.ContinueSession
	if wantResume && initOut.AgentCapabilities.LoadSession {
		loadParams := map[string]any{
			"sessionId":  resumeSessionID,
			"cwd":        s.workDir,
			"mcpServers": []any{},
		}
		loadRes, err := s.tr.call(s.ctx, "session/load", loadParams)
		if err != nil {
			slog.Warn("acp: session/load failed, starting new session", "error", err)
		} else {
			var lr struct {
				SessionID string         `json:"sessionId"`
				Modes     *acpModesBlock `json:"modes"`

View on GitHub (pinned to 4000b2338a)

Solutions

1. Run the agent's login/auth flow separately (e.g. `agent login`) so credentials are valid before cc-connect starts.
2. Check the authMethod id against the methods the agent advertises in its initialize result (authMethods) and update config.
3. Clear the authMethod from config if the agent needs no auth, since authenticate is skipped when it is empty.
4. Re-authenticate to refresh an expired token, then restart cc-connect.

Example fix

// before
auth_method = "oauth-personal"  // agent renamed this id
// after
auth_method = "login-with-api-key"  // id from agent's authMethods list

// verify authMethod against agent-advertised methods after initialize
valid := false
for _, m := range initOut.AuthMethods {
    if m.ID == cfg.AuthMethod { valid = true; break }
}
if cfg.AuthMethod != "" && !valid {
    return fmt.Errorf("auth method %q not offered by agent", cfg.AuthMethod)
}

sess, err := agent.StartSession(ctx, id, nil)
if err != nil && strings.Contains(err.Error(), "acp: authenticate") {
    slog.Error("ACP auth failed — run agent login flow, then restart", "err", err)
    return err
}

When it happens

Trigger: authMethod is set (non-empty after TrimSpace) and the agent returns a JSON-RPC error for `authenticate` — unknown methodId, expired/invalid credentials, or transport/timeout failure during the call.

Common situations: Configured auth_method id does not match one advertised by the agent (agent upgrade renamed method ids); agent not logged in / OAuth token expired; authenticating against an agent that requires a different login flow.

Understand the failure class

• Authentication and authorization failures — expired tokens, bad credentials, and missing scopes.

Related errors

• acp: initialize: %w
• acp: session/new: %w
• acp: parse initialize result: %w
• acp: parse session/new: %w
• acp: session/new: empty sessionId

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