SDK error codes

Updated

List of commonly encountered API errors and their causes.

When interacting with the Agora API, the Video SDK for Web may throw an error code. Receiving an error code indicates that the SDK has encountered an unrecoverable error that requires intervention from your app.

For asynchronous methods, the SDK returns a Promise and throws the appropriate error code when the Promise is rejected. When a synchronous method call fails, the SDK throws an error code directly. The SDK may also throw network-related error codes during internal operation.

The SDK error object AgoraRTCError inherits from the browser Error object. Print the error code with AgoraRTCError.code, because directly printing the AgoraRTCError object only shows the error message.

Common error codes

Error codeDescriptionResolution
UNEXPECTED_ERRORAn unhandled, unexpected error. Usually, this error includes a specific error message.Refer to the specific error message.
UNEXPECTED_RESPONSEThe server returned an unexpected response. This is usually thrown when a network problem causes the client state to be inconsistent with the server state.Wait for the network to stabilize and retry the operation.
INVALID_PARAMSIllegal parameters.Follow the specific prompts and pass the correct parameters according to the documentation.
NOT_SUPPORTEDThe browser does not support the feature.Use a supported browser or feature fallback.
INVALID_OPERATIONIllegal operation. This usually occurs because the operation cannot be performed in the current state.Confirm the order of operations. For example, join the channel before publishing.
OPERATION_ABORTEDThe operation is aborted, usually due to poor network quality or disconnection from the Agora server.Confirm the local network status through AgoraRTCClient.on("user-joined") and retry the operation.
WEB_SECURITY_RESTRICTBrowser security policy restriction.Make sure the page runs in a secure context.
NO_ACTIVE_STATUSThe Agora project is inactive or disabled.Go to Agora Console and confirm that the project is enabled.
Error codeDescriptionResolution
NETWORK_TIMEOUTThe request times out, usually because communication with the Agora server fails due to poor network quality or a broken connection.Confirm local network conditions and retry the operation.
NETWORK_RESPONSE_ERRORResponse error, typically an illegal status code.Verify that the operation parameters are correct.
NETWORK_ERRORUnlocatable network error.Retry after the network stabilizes.
WS_ABORTWebSocket disconnected during a request to the Agora server.Listen to AgoraRTCClient.on("connection-state-change") and retry after the connection state changes to CONNECTED.
WS_DISCONNECTWebSocket disconnected before requesting the Agora server.Listen to AgoraRTCClient.on("connection-state-change") and retry after the connection state changes to CONNECTED.
WS_ERRAn error occurred in the WebSocket connection.Check the current browser support for WebSocket.

Device and track error codes

Error codeDescriptionResolution
ENUMERATE_DEVICES_FAILEDFailed to enumerate local devices, usually due to browser limitations.Check browser permissions and device availability.
DEVICE_NOT_FOUNDThe specified device could not be found.Pass the correct device ID.
TRACK_IS_DISABLEDThe track is disabled, usually because Track.setEnabled() is set to false.Call Track.setEnabled(true) before proceeding.
SHARE_AUDIO_NOT_ALLOWEDThe end user did not click Share Audio when the audio pop-up was presented.Prompt the end user to select Share Audio in the screen sharing pop-up.
MEDIA_OPTION_INVALIDUnsupported parameters for media capture.Modify the media capture parameters or use a preset SDK configuration.
CONSTRAINT_NOT_SATISFIEDUnsupported parameters for media capture.Modify the media capture parameters or use a preset SDK configuration.
PERMISSION_DENIEDPermission to obtain a media device was denied.Select Allow in the device permissions pop-up.
NOT_READABLEThe user is authorized, but the media device is not accessible.Check the current capture device and driver.

Client error codes

Error codeDescriptionResolution
UID_CONFLICTDuplicate UIDs exist in the same channel.Use a different UID to enter the channel.
INVALID_UINT_UID_FROM_STRING_UIDThe string UID allocation service returned an illegal integer UID.Use a different UID to enter the channel.
CAN_NOT_GET_PROXY_SERVERUnable to get the cloud proxy service address.Check the proxy configuration and retry.
CAN_NOT_GET_GATEWAY_SERVERUnable to get the Agora server address.Check the network and retry.
INVALID_LOCAL_TRACKAn illegal LocalTrack was passed in.Check the incoming track and pass a valid LocalTrack.
CAN_NOT_PUBLISH_MULTIPLE_VIDEO_TRACKSA client publishes multiple video tracks.A client can publish only one video track at a time. To publish multiple video tracks, create multiple clients.
INVALID_REMOTE_USERThe remote user is not in the channel or has not published any media tracks.Subscribe only after receiving AgoraRTCClient.on("user-published").
REMOTE_USER_IS_NOT_PUBLISHEDThe remote user has published an audio or video track that does not match the type specified in your subscribe operation.Ensure that the subscribe operation track type matches the published track type.
ERR_TOO_MANY_BROADCASTERSThe number of hosts in the channel exceeds the limit.Control the number of hosts. Switch a user role to host only when the user needs to publish.
ERR_TOO_MANY_SUBSCRIBERSThe number of hosts subscribed to by the current user exceeds the limit.Subscribe to hosts on demand.