Skip to Content
LYNKORIADocs

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

SymptomLikely 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 endpointThe key lacks the scope (calls:write, messaging:write, users:write), or the messaging policy forbids the action.
feature_disabledEnable the feature for this environment in the console.
quota_exceededRoom size, concurrent rooms or tokens-per-minute quota reached. Raise it in the console or end idle calls.
bad_request on joinTokenA host, speaker or viewer role was requested for a non-livestream call.
serviceKey must be a lynk_live_ or lynk_test_ keyThe environment variable is empty or truncated.

The client will not connect

SymptomLikely cause and fix
Stuck on reconnecting, onError reports unauthorizedYour token endpoint failed, or returned something other than { token, expiresAt } or a token string.
Socket rejected from the browserThe page origin is not in Allowed origins, or messaging is disabled for the environment.
Works on localhost, fails in productionThe production origin is missing, or a proxy blocks WebSockets on /socket.io/.
Disconnects after about 10 minutesgetMessagingToken throws during refresh. Check that your session endpoint still works for a long-lived page.

Messages

SymptomLikely cause and fix
not_found for a conversationYou passed your product ID instead of the Lynkoria UUID, or the user is not a member.
Duplicate messages on retryA new clientMessageId was generated per attempt. Reuse the same ID for the same logical message.
Messages appear only after refreshListeners were registered after history loaded, or the client was recreated on every render. Use useConversation or register onMessage first.
Upload failsAttachments must be enabled as a feature and in the messaging policy; check file size and type.

Calls

SymptomLikely cause and fix
NotAllowedError when enabling mediaThe user denied camera or microphone, or the page is not on https:// or localhost.
NotFoundErrorNo camera or microphone is connected.
Connected but no audioNo RoomAudioRenderer, or the browser blocked autoplay; show LiveKit’s StartAudio button.
Join token rejectedMore than 5 minutes passed between issuing and joining; fetch the token inside getJoinToken.
Viewers cannot turn on the cameraExpected: viewer cannot publish. Promote them with calls.setRole(callId, identity, 'speaker').
Connection fails on some networksRestrictive 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

SymptomExplanation
User still online after closing the appThe 60-second lease has not expired yet.
User always offlineThey set invisible, presence is disabled, or they are in a different tenant.
Analytics lag behindCounters flush about every 15 seconds; participant minutes appear when a participant leaves.

Webhooks

SymptomLikely cause and fix
Signature verification failsThe 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 arrivingCheck the console’s Webhooks tab for dead-lettered deliveries and their last error, fix the receiver, then retry.
Duplicate eventsExpected 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.

On this page