What causes "start relay session: %w" in chenhg5/cc-connect?

Run the agent CLI manually in the workspace directory to reproduce the startup failure

start relay session

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.

Solutions

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

Defensive patterns

Strategy: retry

Validate before calling

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

Try / catch

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

Prevention

Verify agent CLI presence and version at startup (cc-connect doctor)
Provide agent provider credentials via env or config before launching sessions
Set explicit, generous session-start timeouts
Distinguish context cancellation from real failures to avoid false alarms

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

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

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