{"record":{"id":"fd478e7d3e43f480","repo":"chenhg5/cc-connect","slug":"relay-w","errorCode":null,"errorMessage":"relay: %w","messagePattern":"relay: %w","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"core/relay.go","lineNumber":259,"sourceCode":"\t}\n\n\t// Post the forwarded message to the group chat for visibility.  The\n\t// default target is \"<platform>:<chatID>:relay\"; platforms that\n\t// understand thread / topic semantics can override this by\n\t// implementing core.RelayGroupVisibilityTarget on their Platform impl.\n\tgroupSessionKey := rm.resolveGroupVisibilityKey(platform, chatID, req.SessionKey, sourceEngine)\n\tif sourceEngine != nil && visibility != RelayVisibilityNone {\n\t\tlabel := relayVisibilityRequestLabel(visibility, fromName, toName, req.Message)\n\t\trm.sendToGroup(ctx, sourceEngine, platform, groupSessionKey, label)\n\t}\n\n\t// Execute relay: inject message into target engine and collect response\n\trelayCtx, cancel := rm.relayContext(ctx)\n\tdefer cancel()\n\n\tresponse, err := targetEngine.HandleRelay(relayCtx, req.From, req.SessionKey, req.Message)\n\tif err != nil {\n\t\treturn nil, fmt.Errorf(\"relay: %w\", err)\n\t}\n\n\t// Post the response to the group chat for visibility.\n\tif targetEngine != nil && visibility != RelayVisibilityNone {\n\t\tlabel := relayVisibilityResponseLabel(visibility, toName, response)\n\t\trm.sendToGroup(ctx, targetEngine, platform, groupSessionKey, label)\n\t}\n\n\treturn &RelayResponse{Response: response}, nil\n}\n\n// sendToGroup sends a message to the group chat for visibility.\nfunc (rm *RelayManager) sendToGroup(ctx context.Context, e *Engine, platform, sessionKey, content string) {\n\tfor _, p := range e.platforms {\n\t\tif p.Name() != platform {\n\t\t\tcontinue\n\t\t}\n\t\trc, ok := p.(ReplyContextReconstructor)","sourceCodeStart":241,"sourceCodeEnd":277,"githubUrl":"https://github.com/chenhg5/cc-connect/blob/4000b2338aa6e850c99df54f8b0ed6ed7460b401/core/relay.go#L241-L277","documentation":"Wrap-around error from RelayManager.Send: the target engine's HandleRelay call returned an error, which Send re-wraps with the 'relay:' prefix. The root cause is inside the target engine's relay handling (session creation, message injection, agent process failure, or the relay context timeout expiring).","triggerScenarios":"targetEngine.HandleRelay(relayCtx, ...) returns any error: agent process failed to start, the target session errored, the relay timeout (rm.timeout) elapsed and cancelled relayCtx, or the target agent rejected the message.","commonSituations":"Relay timeout too short for a slow agent response; target agent CLI not installed or failing auth; target session in a bad state; context cancellation propagated from an upstream user cancel.","solutions":["Unwrap the error (%w chain) to find the root cause from HandleRelay","Increase the relay timeout configuration if the message was slow and the deadline fired","Verify the target agent CLI is installed, authenticated, and healthy (run its doctor command)","Inspect the target engine's logs at the time of the relay for the underlying failure"],"exampleFix":"// before: opaque handling\nresp, err := rm.Send(ctx, req)\nif err != nil { log.Print(err) } // \"relay: context deadline exceeded\"\n// after: unwrap to the root cause\nif err != nil { log.Printf(\"relay root cause: %v\", errors.Unwrap(err)) }","handlingStrategy":"try-catch","validationCode":"// pre-check what HandleRelay depends on\nif rm.RelayTimeout() > 0 && rm.RelayTimeout() < 30*time.Second { log.Warn(\"relay timeout very low\") }\nif err := targetAgent.HealthCheck(ctx); err != nil { return fmt.Errorf(\"target agent unhealthy: %w\", err) }","typeGuard":null,"tryCatchPattern":"resp, err := rm.Send(ctx, req)\nif err != nil {\n\tif errors.Is(err, context.DeadlineExceeded) {\n\t\treply(\"Relay timed out; try again or increase the relay timeout.\")\n\t\treturn\n\t}\n\treply(\"Relay failed: \" + errors.Unwrap(err).Error())\n\treturn\n}","preventionTips":["Set a realistic relay timeout in config (target agents can take minutes)","Keep target agent CLIs installed and authenticated; run doctor regularly","Unwrap %w chains with errors.Is/As instead of string matching"],"tags":["relay","error-wrapping","agent"],"backgroundTag":"upstream-api-error","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"}