Troubleshooting integration

Symptoms mapped to fixes you can paste into your app or curl.

401 Unauthorized / invalid API key

Symptom: REST returns 401; FluxyAuthError on connect.

Checks:

API key belongs to the project you expect (Projects console or POST /dev/provision in local dev).
Header is X-Fluxy-Api-Key: fc_... (server-side only).
Worker URL matches the project (NEXT_PUBLIC_FLUXYCHAT_WORKER_URL).

curl -sS -X POST "$FLUXY_BASE_URL/auth/token" \
  -H "Content-Type: application/json" \
  -H "X-Fluxy-Api-Key: $FLUXY_API_KEY" \
  -d '{"userId":"test","roles":["member"],"ttlSeconds":300}'

Token expired

Symptom: FluxyTokenExpiredError, WS close reason token_expired.

Fix: Mint a fresh JWT — the SDK has no updateToken() helper. Refresh via your backend:

const res = await fetch("/api/fluxy/token", { method: "POST" });
const { token } = await res.json();
// pass token to FluxyRealtimeProvider authTokenProvider or new FluxyChatClient

Use ttlSeconds with buffer; refresh before exp (dashboard uses ~5 min buffer).

Not a room member

Symptom: FluxyNotMemberError, WS 1008 Forbidden.

Fix: Add the user to the room or join with a JWT whose sub is a member:

curl -sS -X POST "$FLUXY_BASE_URL/rooms/$ROOM_ID/members" \
  -H "X-Fluxy-Api-Key: $FLUXY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"userId":"alice","role":"member"}'

Connection degraded / reconnect loop

Symptom: connectionStatus is degraded, degraded-http, or reconnecting.

Checks:

Worker reachable: curl $FLUXY_BASE_URL/health
CORS / mixed content (HTTPS page → HTTP worker blocked in prod)
Rate limits — RateLimitError with retryAfterMs

Use getConnectionStatusLabel() from @fluxy-chat/sdk for user-facing copy.

Messages not appearing

Confirm JWT sub matches sender you expect.
Check roomId spelling (project-scoped ids like {projectId}-general).
For history: call loadHistory() / wait for historyLoaded in useChat.

Local dev checklist

pnpm run first-message   # provisions dev-local, sends first message
pnpm run smoke:create-fluxy-chat

Worker needs ALLOW_DEV_PROVISION=true in apps/worker/.dev.vars for local provision.