chenhg5/cc-connect · error

start relay session: %w

Error message

start relay session: %w

What it means

In the relay flow, after possibly reusing or restarting a relay session, agent.StartSession failed and the error is wrapped as 'start relay session: %w'. Note the code retries with an empty session ID once (recovery path) — this error means even the fresh-start attempt failed, so the agent process could not be launched or the handshake with the agent CLI did not complete.

Source

Thrown at core/engine.go:15998

		inj.SetSessionEnv(envVars)
	}

	// Use the engine context (not the relay timeout context) so that the
	// agent process is not killed when the relay deadline fires. The relay
	// timeout only controls how long we *wait* for the response.
	agentSession, err := agent.StartSession(e.ctx, session.GetAgentSessionID())
	if err != nil {
		// Resume failed — fall back to a fresh session so the relay is not
		// permanently broken by a corrupted/stale session ID.
		if session.GetAgentSessionID() != "" {
			slog.Warn("relay: session resume failed, trying fresh session",
				"relay_key", relaySessionKey, "error", err)
			session.SetAgentSessionID("", agent.Name())
			sessions.Save()
			agentSession, err = agent.StartSession(e.ctx, "")
		}
		if err != nil {
			return "", fmt.Errorf("start relay session: %w", err)
		}
	}

	saveRelaySessionID := func(id string, force bool) {
		if id == "" {
			return
		}
		changed := false
		if force {
			session.SetAgentSessionID(id, agent.Name())
			changed = true
		} else {
			changed = session.CompareAndSetAgentSessionID(id, agent.Name())
		}
		if !changed {
			return
		}
		pendingName := session.GetName()

View on GitHub (pinned to 4000b2338a)

Solutions

1. Run the agent CLI manually in the workspace directory to reproduce the startup failure
2. Check agent provider credentials (API keys/env vars) available to the cc-connect process
3. Verify the agent CLI version is supported (cc-connect doctor)
4. Reduce concurrent sessions or restart cc-connect if resource-limited
5. Check e.ctx wasn't cancelled — if so, this error is a symptom of shutdown, not a real failure

bin := "claude" // agent CLI name
if _, err := exec.LookPath(bin); err != nil {
    return fmt.Errorf("agent CLI %q not found: %w", bin, err)
}
if os.Getenv("ANTHROPIC_API_KEY") == "" {
    return fmt.Errorf("agent API key missing")
}

agentSession, err := agent.StartSession(e.ctx, "")
if err != nil {
    if errors.Is(err, context.Canceled) {
        return "", err // shutdown in progress
    }
    select {
    case <-time.After(2 * time.Second):
        agentSession, err = agent.StartSession(e.ctx, "") // one retry
    case <-e.ctx.Done():
        return "", e.ctx.Err()
    }
}

When it happens

Trigger: agent.StartSession(e.ctx, "") returns an error on the retry path — agent CLI binary fails to launch, exits immediately, times out during initialization, or the context is cancelled.

Common situations: Agent CLI not installed or wrong version; API key for the agent provider missing/expired (agent exits at startup); workspace directory invalid as a working directory; resource exhaustion (too many concurrent sessions); e.ctx cancelled by shutdown.

Related errors

• send relay message: %w
• get relay workspace agent: %w
• agent error (no details)
• relay: %w
• acp: agent option "cmd" or "command" is required (path or na

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