Docs / Appendix / Troubleshooting
Troubleshooting
Symptom-first index: join failures, no video, missing recordings, missing callbacks, token expiry, CORS and firewalls.
Version v1.1.0 · Updated 2026-10-26 · revision 1
Indexed by the symptom you see. Every row states what to check first, how to check it, and what the root cause is — do not change code on a hunch.
Joining and authentication#
Symptom Check first Common root cause Fix
401 missing_authorization request headers Authorization: Basic … was left outadd base64(customerId:customerSecret) 401 invalid_credentials the credentials page in the console the secret is the old value from before rotation update the environment variables and restart the service 401 invalid_appid whether customerId and appId belong to the same project credentials reused across projects one set of credentials per project 400 invalid_channel_name the channel-name character set contains spaces/non-ASCII/too long use [A-Za-z0-9_-], ≤128 403 banned GET /dev/v1/kicking-rulematched a join_channel ban delete the ban rule 403 service_not_enabled the project services page recording/streaming not enabled enable it and retry SDK reports -110 / INVALID_TOKEN GET /v1/tokens/verify?token=&channelName=the token does not match the channel/appId, or has expired issue a new one; check pexp SDK reports -109 / TOKEN_EXPIRE exp in the token payloadthe token lifetime is over rejoin with a new token Kicked right after joining callback log 104/108 the same uid joined somewhere else (uid conflict) use a unique uid per client
Symptom Check first Common root cause Fix
Audio only, no video the user-published callback no subscribe, or no play(containerId) add the subscribe and render calls The local preview is black but the remote side can see it cameraTrack.play()the container id does not exist or has zero size check the DOM/container and the CSS The other side cannot see me whether publish succeeded audience role / the token has no publish_* privileges switch to the host role and re-issue the token Stuck in RECONNECTING the SFU address resolution chain the reverse proxy does not allow WebSocket enable Upgrade pass-through Screen share is black the capture source protected window / macOS permission missing share the whole screen; grant permission in System Settings and restart Stutters on a weak network without degrading whether dual stream is on the publisher did not enable dual stream enableDualStream()Video is upside down or mirrored the render layer front-camera mirroring adjust mirrorMode
Recording#
Symptom Check first Common root cause Fix
403 service_not_enabledproject services recording not enabled enable it 429 recording_quota_exceededdetails.limit / details.activeconcurrent recordings at the cap queue, or raise the quota — see Quota start fails after acquire the time gap resourceId has only a 30-second TTLstart immediately; do not store it for later The job stays starting GET /v1/recordings/{id}the egress node is unavailable / the queue is full check the operator surface Recording completes but the file 404s storage vendor configuration bucket permissions or path prefix are wrong run the recording-storage self-check The recording is black nobody publishing in the channel nobody was on stage when recording started join first, then record, or extend the wait
Streaming / pulling / gateway#
Symptom Check first Common root cause Fix
converter state=failed the error in callback 202 the RTMP address refused the connection verify the address with ffmpeg/OBS OBS ingest rejected streamkey expired, channel mismatch, or the template does not exist re-issue the streamkey The stream is in the channel but not visible online-streamsthe ingest never established a session check the gateway handshake log and sid Pull status=failed the player detail error the source address is unreachable (private network/localhost) switch to a URL the server can reach Pulled video has no audio audioOptionsmuted by default, or the track is missing check whether the source has an audio track
Callbacks#
Symptom Check first Common root cause Fix
Nothing arrives at all webhook configuration not configured / enabled:false configure it in the console It arrives but signature verification fails which body you verify re-serializing after deserialization verify against the raw bytes Only some events arrive the subscribed event list the event is not ticked add the subscription The delivery log is all 4xx your receiver path 404 / missing Content-Type fix the receiver Gives up after 9 retries delivery log the receiver returned 5xx for a long time fix it, then replay manually
Self-check order#
Is the API alive? curl -s $NIMEET_API_BASE/healthz Do the credentials work? Issue a token with POST /v1/tokens and verify it with GET /v1/tokens/verify. Does the full path work? Join a channel with the Web SDK or a client SDK and publish a track. Do callbacks arrive? Configure the webhook and check GET /v1/webhook/deliveries. If everything is green and you still cannot pin the problem down, include the X-Request-Id and the time of the error in your support request — every server log, callback delivery and audit record carries that id.
Related pages#