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 code | Description | Resolution |
|---|---|---|
UNEXPECTED_ERROR | An unhandled, unexpected error. Usually, this error includes a specific error message. | Refer to the specific error message. |
UNEXPECTED_RESPONSE | The 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_PARAMS | Illegal parameters. | Follow the specific prompts and pass the correct parameters according to the documentation. |
NOT_SUPPORTED | The browser does not support the feature. | Use a supported browser or feature fallback. |
INVALID_OPERATION | Illegal 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_ABORTED | The 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_RESTRICT | Browser security policy restriction. | Make sure the page runs in a secure context. |
NO_ACTIVE_STATUS | The Agora project is inactive or disabled. | Go to Agora Console and confirm that the project is enabled. |
Request-related error codes
| Error code | Description | Resolution |
|---|---|---|
NETWORK_TIMEOUT | The 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_ERROR | Response error, typically an illegal status code. | Verify that the operation parameters are correct. |
NETWORK_ERROR | Unlocatable network error. | Retry after the network stabilizes. |
WS_ABORT | WebSocket 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_DISCONNECT | WebSocket disconnected before requesting the Agora server. | Listen to AgoraRTCClient.on("connection-state-change") and retry after the connection state changes to CONNECTED. |
WS_ERR | An error occurred in the WebSocket connection. | Check the current browser support for WebSocket. |
Device and track error codes
| Error code | Description | Resolution |
|---|---|---|
ENUMERATE_DEVICES_FAILED | Failed to enumerate local devices, usually due to browser limitations. | Check browser permissions and device availability. |
DEVICE_NOT_FOUND | The specified device could not be found. | Pass the correct device ID. |
TRACK_IS_DISABLED | The track is disabled, usually because Track.setEnabled() is set to false. | Call Track.setEnabled(true) before proceeding. |
SHARE_AUDIO_NOT_ALLOWED | The 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_INVALID | Unsupported parameters for media capture. | Modify the media capture parameters or use a preset SDK configuration. |
CONSTRAINT_NOT_SATISFIED | Unsupported parameters for media capture. | Modify the media capture parameters or use a preset SDK configuration. |
PERMISSION_DENIED | Permission to obtain a media device was denied. | Select Allow in the device permissions pop-up. |
NOT_READABLE | The user is authorized, but the media device is not accessible. | Check the current capture device and driver. |
Client error codes
| Error code | Description | Resolution |
|---|---|---|
UID_CONFLICT | Duplicate UIDs exist in the same channel. | Use a different UID to enter the channel. |
INVALID_UINT_UID_FROM_STRING_UID | The string UID allocation service returned an illegal integer UID. | Use a different UID to enter the channel. |
CAN_NOT_GET_PROXY_SERVER | Unable to get the cloud proxy service address. | Check the proxy configuration and retry. |
CAN_NOT_GET_GATEWAY_SERVER | Unable to get the Agora server address. | Check the network and retry. |
INVALID_LOCAL_TRACK | An illegal LocalTrack was passed in. | Check the incoming track and pass a valid LocalTrack. |
CAN_NOT_PUBLISH_MULTIPLE_VIDEO_TRACKS | A 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_USER | The 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_PUBLISHED | The 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_BROADCASTERS | The 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_SUBSCRIBERS | The number of hosts subscribed to by the current user exceeds the limit. | Subscribe to hosts on demand. |