chenhg5/cc-connect · error

relay not available

Error message

relay not available

What it means

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.

Source

Thrown at core/api.go:766

	}

	if !s.timer.RemoveJob(req.ID) {
		http.Error(w, "timer not found", http.StatusNotFound)
		return
	}

	apiJSON(w, http.StatusOK, map[string]string{"status": "ok", "id": req.ID})
}

// ── Relay API ──────────────────────────────────────────────────

func (s *APIServer) handleRelaySend(w http.ResponseWriter, r *http.Request) {
	if r.Method != http.MethodPost {
		http.Error(w, "POST only", http.StatusMethodNotAllowed)
		return
	}
	if s.relay == nil {
		http.Error(w, "relay not available", http.StatusServiceUnavailable)
		return
	}

	var req RelayRequest
	if err := json.NewDecoder(r.Body).Decode(&req); err != nil {
		http.Error(w, "invalid JSON: "+err.Error(), http.StatusBadRequest)
		return
	}
	if req.To == "" || req.Message == "" || req.SessionKey == "" {
		http.Error(w, "to, session_key, and message are required", http.StatusBadRequest)
		return
	}

	resp, err := s.relay.Send(r.Context(), req)
	if err != nil {
		http.Error(w, err.Error(), http.StatusInternalServerError)
		return
	}

View on GitHub (pinned to 4000b2338a)

Solutions

1. Enable the relay in config.toml and restart cc-connect
2. Check startup logs for relay initialization errors
3. Feature-detect relay availability before calling, or handle 503 gracefully in clients
4. Confirm you are pointing at the correct server instance (one with relay enabled)

Example fix

// config.toml before
# (no [relay] section)
// after
[relay]
enabled = true

const health = await (await fetch('/api/health')).json();
if (!health.relayEnabled) console.warn('relay unavailable; skipping relay send');

try { await relaySend(req); } catch (e) { if (e.status === 503) { queueForLater(req); return; } throw e; }

When it happens

Trigger: POST to relay-send when the server was built without a relay (relay disabled in config, not wired in NewAPIServer, or relay startup failed).

Common situations: 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.

Related errors

• timer scheduler not available
• invalid source session key: %w
• resolve relay workspace: %w
• workspace binding unavailable for source channel %q
• no workspace binding for source channel %q

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