{"record":{"id":"a2b00117c9856653","repo":"chenhg5/cc-connect","slug":"start-relay-session-w","errorCode":null,"errorMessage":"start relay session: %w","messagePattern":"start relay session: %w","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"core/engine.go","lineNumber":15998,"sourceCode":"\t\tinj.SetSessionEnv(envVars)\n\t}\n\n\t// Use the engine context (not the relay timeout context) so that the\n\t// agent process is not killed when the relay deadline fires. The relay\n\t// timeout only controls how long we *wait* for the response.\n\tagentSession, err := agent.StartSession(e.ctx, session.GetAgentSessionID())\n\tif err != nil {\n\t\t// Resume failed — fall back to a fresh session so the relay is not\n\t\t// permanently broken by a corrupted/stale session ID.\n\t\tif session.GetAgentSessionID() != \"\" {\n\t\t\tslog.Warn(\"relay: session resume failed, trying fresh session\",\n\t\t\t\t\"relay_key\", relaySessionKey, \"error\", err)\n\t\t\tsession.SetAgentSessionID(\"\", agent.Name())\n\t\t\tsessions.Save()\n\t\t\tagentSession, err = agent.StartSession(e.ctx, \"\")\n\t\t}\n\t\tif err != nil {\n\t\t\treturn \"\", fmt.Errorf(\"start relay session: %w\", err)\n\t\t}\n\t}\n\n\tsaveRelaySessionID := func(id string, force bool) {\n\t\tif id == \"\" {\n\t\t\treturn\n\t\t}\n\t\tchanged := false\n\t\tif force {\n\t\t\tsession.SetAgentSessionID(id, agent.Name())\n\t\t\tchanged = true\n\t\t} else {\n\t\t\tchanged = session.CompareAndSetAgentSessionID(id, agent.Name())\n\t\t}\n\t\tif !changed {\n\t\t\treturn\n\t\t}\n\t\tpendingName := session.GetName()","sourceCodeStart":15980,"sourceCodeEnd":16016,"githubUrl":"https://github.com/chenhg5/cc-connect/blob/4000b2338aa6e850c99df54f8b0ed6ed7460b401/core/engine.go#L15980-L16016","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","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"],"exampleFix":null,"handlingStrategy":"retry","validationCode":"bin := \"claude\" // agent CLI name\nif _, err := exec.LookPath(bin); err != nil {\n    return fmt.Errorf(\"agent CLI %q not found: %w\", bin, err)\n}\nif os.Getenv(\"ANTHROPIC_API_KEY\") == \"\" {\n    return fmt.Errorf(\"agent API key missing\")\n}","typeGuard":null,"tryCatchPattern":"agentSession, err := agent.StartSession(e.ctx, \"\")\nif err != nil {\n    if errors.Is(err, context.Canceled) {\n        return \"\", err // shutdown in progress\n    }\n    select {\n    case <-time.After(2 * time.Second):\n        agentSession, err = agent.StartSession(e.ctx, \"\") // one retry\n    case <-e.ctx.Done():\n        return \"\", e.ctx.Err()\n    }\n}","preventionTips":["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"],"tags":["agent","session","relay","process-start"],"backgroundTag":"command-not-found","analyzedSha":"4000b2338aa6e850c99df54f8b0ed6ed7460b401","analyzedAt":"2026-09-06T11:45:09.575Z","contentChangedAt":"2026-09-06T11:45:09.575Z","schemaVersion":2},"datasetVersion":"2026-09-14T05:17:10.506Z"}