Troubleshooting
Fix the most common integration problems with keys, tokens, sockets, calls, messages and webhooks.
Start with the error’s code and requestId (see errors). The Playground’s event log shows every SDK call, socket event and media event with timings, which makes it a quick way to reproduce a problem against your project.
Backend requests fail
| Symptom | Likely cause and fix |
|---|---|
unauthorized · “Invalid service key” | Wrong or revoked key, or a test key against a production deployment (or the reverse). Check the prefix and the console. |
forbidden on a call or message endpoint | The key lacks the scope (calls:write, messaging:write, users:write), or the messaging policy forbids the action. |
feature_disabled | Enable the feature for this environment in the console. |
quota_exceeded | Room size, concurrent rooms or tokens-per-minute quota reached. Raise it in the console or end idle calls. |
bad_request on joinToken | A host, speaker or viewer role was requested for a non-livestream call. |
serviceKey must be a lynk_live_ or lynk_test_ key | The environment variable is empty or truncated. |
The client will not connect
| Symptom | Likely cause and fix |
|---|---|
Stuck on reconnecting, onError reports unauthorized | Your token endpoint failed, or returned something other than { token, expiresAt } or a token string. |
| Socket rejected from the browser | The page origin is not in Allowed origins, or messaging is disabled for the environment. |
Works on localhost, fails in production | The production origin is missing, or a proxy blocks WebSockets on /socket.io/. |
| Disconnects after about 10 minutes | getMessagingToken throws during refresh. Check that your session endpoint still works for a long-lived page. |
Messages
| Symptom | Likely cause and fix |
|---|---|
not_found for a conversation | You passed your product ID instead of the Lynkoria UUID, or the user is not a member. |
| Duplicate messages on retry | A new clientMessageId was generated per attempt. Reuse the same ID for the same logical message. |
| Messages appear only after refresh | Listeners were registered after history loaded, or the client was recreated on every render. Use useConversation or register onMessage first. |
| Upload fails | Attachments must be enabled as a feature and in the messaging policy; check file size and type. |
Calls
| Symptom | Likely cause and fix |
|---|---|
NotAllowedError when enabling media | The user denied camera or microphone, or the page is not on https:// or localhost. |
NotFoundError | No camera or microphone is connected. |
| Connected but no audio | No RoomAudioRenderer, or the browser blocked autoplay; show LiveKit’s StartAudio button. |
| Join token rejected | More than 5 minutes passed between issuing and joining; fetch the token inside getJoinToken. |
| Viewers cannot turn on the camera | Expected: viewer cannot publish. Promote them with calls.setRole(callId, identity, 'speaker'). |
| Connection fails on some networks | Restrictive firewalls block UDP. Media falls back to TCP and TURN when the deployment provides them; report the network to the platform team. |
Presence and usage
| Symptom | Explanation |
|---|---|
| User still online after closing the app | The 60-second lease has not expired yet. |
| User always offline | They set invisible, presence is disabled, or they are in a different tenant. |
| Analytics lag behind | Counters flush about every 15 seconds; participant minutes appear when a participant leaves. |
Webhooks
| Symptom | Likely cause and fix |
|---|---|
| Signature verification fails | The body was parsed or re-serialized before verifying. Verify the raw bytes. |
| “Signature timestamp outside tolerance” | Your server clock is off by more than 5 minutes; enable NTP. |
| Events stop arriving | Check the console’s Webhooks tab for dead-lettered deliveries and their last error, fix the receiver, then retry. |
| Duplicate events | Expected with at-least-once delivery; deduplicate on id. |
Still stuck? Send the platform team the requestId, environment, time window and what you expected. Never include keys or tokens.