{"record":{"id":"6c6b871f57e9088b","repo":"chenhg5/cc-connect","slug":"relay-not-available","errorCode":null,"errorMessage":"relay not available","messagePattern":"relay not available","errorType":"http","errorClass":null,"httpStatus":503,"severity":"error","filePath":"core/api.go","lineNumber":766,"sourceCode":"\t}\n\n\tif !s.timer.RemoveJob(req.ID) {\n\t\thttp.Error(w, \"timer not found\", http.StatusNotFound)\n\t\treturn\n\t}\n\n\tapiJSON(w, http.StatusOK, map[string]string{\"status\": \"ok\", \"id\": req.ID})\n}\n\n// ── Relay API ──────────────────────────────────────────────────\n\nfunc (s *APIServer) handleRelaySend(w http.ResponseWriter, r *http.Request) {\n\tif r.Method != http.MethodPost {\n\t\thttp.Error(w, \"POST only\", http.StatusMethodNotAllowed)\n\t\treturn\n\t}\n\tif s.relay == nil {\n\t\thttp.Error(w, \"relay not available\", http.StatusServiceUnavailable)\n\t\treturn\n\t}\n\n\tvar req RelayRequest\n\tif err := json.NewDecoder(r.Body).Decode(&req); err != nil {\n\t\thttp.Error(w, \"invalid JSON: \"+err.Error(), http.StatusBadRequest)\n\t\treturn\n\t}\n\tif req.To == \"\" || req.Message == \"\" || req.SessionKey == \"\" {\n\t\thttp.Error(w, \"to, session_key, and message are required\", http.StatusBadRequest)\n\t\treturn\n\t}\n\n\tresp, err := s.relay.Send(r.Context(), req)\n\tif err != nil {\n\t\thttp.Error(w, err.Error(), http.StatusInternalServerError)\n\t\treturn\n\t}","sourceCodeStart":748,"sourceCodeEnd":784,"githubUrl":"https://github.com/chenhg5/cc-connect/blob/4000b2338aa6e850c99df54f8b0ed6ed7460b401/core/api.go#L748-L784","documentation":"HTTP 503 response from the relay-send API endpoint: the APIServer was constructed without a relay component (relay feature not enabled/configured), so the handler refuses to process relay sends.","triggerScenarios":"POST to relay-send when the server was built without a relay (relay disabled in config, not wired in NewAPIServer, or relay startup failed).","commonSituations":"Deployments without the relay feature; partial startup where relay initialization failed but the API server still runs; stale clients targeting a server whose relay was turned off.","solutions":["Enable the relay in config.toml and restart cc-connect","Check startup logs for relay initialization errors","Feature-detect relay availability before calling, or handle 503 gracefully in clients","Confirm you are pointing at the correct server instance (one with relay enabled)"],"exampleFix":"// config.toml before\n# (no [relay] section)\n// after\n[relay]\nenabled = true","handlingStrategy":"fallback","validationCode":"const health = await (await fetch('/api/health')).json();\nif (!health.relayEnabled) console.warn('relay unavailable; skipping relay send');","typeGuard":null,"tryCatchPattern":"try { await relaySend(req); } catch (e) { if (e.status === 503) { queueForLater(req); return; } throw e; }","preventionTips":["Enable the relay in config.toml on servers that must send relay messages","Check startup logs for relay initialization errors","Confirm the client targets a server instance with relay enabled"],"tags":["http-api","service-unavailable","relay"],"backgroundTag":"feature-not-enabled","analyzedSha":"4000b2338aa6e850c99df54f8b0ed6ed7460b401","analyzedAt":"2026-09-06T11:45:09.575Z","contentChangedAt":"2026-09-06T11:45:09.575Z","schemaVersion":2},"datasetVersion":"2026-09-14T00:17:10.932Z"}