VideoSDK provides the error event which informs you about any error happening during the room. Actions that fail also throw a VideoSDKError.
- This event is triggered whenever an invalid configuration is provided or server/network errors arise. In such cases, the event will trigger with a specific error code and message.
- It is particularly useful for development-level troubleshooting during SDK integration.
- It can be subscribed to using the
Room object.
- The handler receives a
VideoSDKError with code (an int), name and message. Check the code, not the message, which the server can replace with its own.
Room, Participant and RTCStream actions, such as join(), return a Future that throws a VideoSDKError when the action fails. It carries the same code, name and message. Await these actions inside try/catch. To learn more, see Error Handling.VideoSDK.createCameraVideoTrack(), VideoSDK.createMicrophoneAudioTrack() and VideoSDK.createScreenShareVideoTrack() throw a VideoSDKError when they fail, so catch it where you call them. The pre-call test fails with a PreCallTestException instead. See Pre-call test errors.- Some failures reach both your
catch block and Events.error, for example a failed room.send() (3070). Handle each error in one place.
- On Android, most actions called while the room reconnects report
3065 on Events.error and return without throwing, so keep an Events.error handler as well.
Here is an example demonstrating the usage of the event mentioned on this page.
import 'dart:developer';
import 'package:flutter/material.dart';
import 'package:videosdk/videosdk.dart';
class RoomScreen extends StatefulWidget {
}
class _RoomScreenState extends State<RoomScreen> {
late Room room;
@override
void initState() {
super.initState();
setupRoomEventListener();
}
@override
Widget build(BuildContext context) {
return YourRoomWidget();
}
void setupRoomEventListener() {
room.on(Events.error, (VideoSDKError error) {
log("VIDEOSDK ERROR :: ${error.code} :: ${error.name} :: ${error.message}");
});
}
}
Catch the VideoSDKError that a failed action throws:
try {
await room.join();
} on VideoSDKError catch (error) {
log("VIDEOSDK ERROR :: ${error.code} :: ${error.name} :: ${error.message}");
}
We have depicted a specific constant with code and message in the below table.
The SDK names code 4009 MAX_PARTCIPANT_REACHED and code 4023 UNAUTHORIZED_PARTCIPANT_ID. Compare these errors by code.
This table lists errors that occur due to the configuration and limitations within your organization’s account. These include account status, participant limits, and add-on service availability.
| Name | Code | Message |
|---|
| ACCOUNT_DEACTIVATED | 4006 | Your account has been deactivated. Please contact VideoSDK support. |
| ACCOUNT_DISCONTINUED | 4007 | Your account has been discontinued. Please reach out to support for more details. |
| MAX_PARTICIPANT_REACHED | 4009 | You have reached the maximum participant limit for this meeting. |
| MAX_SPEAKER_REACHED | 4010 | The maximum number of speakers for this meeting has been reached. |
| MAX_SPEAKER_LIMIT_REACHED_ON_ORGANIZATION | 4026 | Your organization has reached the maximum number of speakers allowed. |
| MAX_VIEWER_LIMIT_REACHED_ON_ORGANIZATION | 4027 | Your organization has reached the maximum number of viewers allowed. |
| ADD_ON_SERVICES_DISABLED | 4021 | Add-On services have been disabled. Please contact support to enable them. |
| MAX_RECORDING_LIMIT_REACHED_ON_ORGANIZATION | 4028 | You have reached max limit of recording on organization. To increase contact at support@videosdk.live |
| MAX_HLS_LIMIT_REACHED_ON_ORGANIZATION | 4029 | You have reached max limit of hls on organization. To increase contact at support@videosdk.live |
| MAX_LIVESTREAM_LIMIT_REACHED_ON_ORGANIZATION | 4030 | You have reached max limit of livestream on organization. To increase contact at support@videosdk.live |
| MAX_RECV_ONLY_LIMIT_REACHED_ON_ORGANIZATION | 4041 | Your organization has reached the maximum recv-only limit. To increase contact at support@videosdk.live |
Errors listed here are related to issues with the API key, authentication tokens, or permissions assigned to users. These errors can occur when tokens are missing, expired, or improperly configured.
| Name | Code | Message |
|---|
| INVALID_API_KEY | 4001 | The provided API key is either missing or invalid. |
| INVALID_TOKEN | 4002 | The provided token is empty, invalid, or has expired. |
| INVALID_PERMISSIONS | 4008 | The permissions in the token are incorrect. Please verify them. |
| UNAUTHORIZED_MEETING_ID | 4022 | The provided token is not authorized for this meeting ID. |
| UNAUTHORIZED_PARTICIPANT_ID | 4023 | The provided token is not authorized for this participant ID. |
| UNAUTHORIZED_ROLE | 4024 | The role specified in the token is not valid for joining this meeting. |
| UNAUTHORIZED_REQUEST | 4025 | Your request does not match the security configuration. |
| APIKEY_DEACTIVATED | 4053 | The provided API key is deactivated. Please verify it on the dashboard. |
This table lists errors resulting from invalid or missing meeting or participant details, including cases where a participant attempts to join with a duplicate ID.
| Name | Code | Message |
|---|
| INVALID_MEETING_ID | 4003 | The meeting ID provided is either invalid or missing. |
| INVALID_PARTICIPANT_ID | 4004 | The participant ID is either invalid or missing. |
| DUPLICATE_PARTICIPANT | 4005 | This participant has joined from another device. |
| MEETING_ID_DISABLED | 4052 | The provided meeting ID is disabled. Please generate a new meetingId using the API. |
This section addresses errors that occur while using VideoSDK's add-on services such as recording, livestreaming, HLS streaming, and transcription.
| Name | Code | Message |
|---|
| START_RECORDING_FAILED | 4011 | Failed to start recording. Please try again. |
| STOP_RECORDING_FAILED | 4012 | Failed to stop recording. Please try again. |
| RECORDING_FAILED | 5001 | Recording was stopped due to an error. |
| START_PARTICIPANT_RECORDING_FAILED | 4035 | Failed to start participant recording. Please check the request. |
| STOP_PARTICIPANT_RECORDING_FAILED | 4036 | Failed to stop participant recording. |
| PARTICIPANT_RECORDING_FAILED | 5012 | Participant recording has stopped due to an error. |
| START_TRACK_RECORDING_FAILED | 4037 | Failed to start track recording. |
| STOP_TRACK_RECORDING_FAILED | 4038 | Failed to stop track recording. |
| TRACK_RECORDING_FAILED | 5013 | Track recording stopped due to an unknown error. |
| PREV_RECORDING_PROCESSING | 4018 | Previous recording session is being processed, please try again after few seconds. |
| RECORDING_DURATION_LIMIT_REACHED | 5004 | Recording stopped due to maximum duration being reached. |
| START_COMPOSITE_RECORDING_FAILED | 4039 | Failed to start composite recording. Please try again. |
| STOP_COMPPOSITE_RECORDING_FAILED | 4040 | Failed to stop composite recording. Please try again. |
| Name | Code | Message |
|---|
| INVALID_LIVESTREAM_CONFIG | 4015 | Livestream 'outputs' configuration provided was invalid |
| START_LIVESTREAM_FAILED | 4013 | Failed to start livestream. Please try again. |
| STOP_LIVESTREAM_FAILED | 4014 | Failed to stop livestream. Please try again. |
| LIVESTREAM_FAILED | 5002 | Livestream stopped due to an error. |
| PREV_RTMP_RECORDING_PROCESSING | 4019 | Previous RTMP recording session is being processed, please try again after few seconds! |
| LIVESTREAM_DURATION_LIMIT_REACHED | 5005 | Livestream stopped due to maximum duration being reached. |
| Name | Code | Message |
|---|
| START_HLS_FAILED | 4016 | Failed to start HLS stream. |
| STOP_HLS_FAILED | 4017 | Failed to stop HLS stream. |
| HLS_FAILED | 5003 | HLS streaming stopped due to an error. |
| PREV_HLS_STREAMING_PROCESSING | 4020 | Previous HLS streaming session is still being processed. |
| HLS_DURATION_LIMIT_REACHED | 5006 | HLS stream stopped due to maximum duration being reached. |
| Name | Code | Message |
|---|
| START_TRANSCRIPTION_FAILED | 4031 | Failed to start transcription. Please try again. |
| STOP_TRANSCRIPTION_FAILED | 4032 | Failed to stop transcription. |
| TRANSCRIPTION_FAILED | 5007 | Transcription stopped due to an error. |
These errors involve media access, device availability, or permission-related issues affecting camera, microphone, and screen sharing.
| Name | Code | Message |
|---|
| ERROR_GET_DISPLAY_MEDIA_PERMISSION_DENIED | 3016 | Screen sharing permission denied. |
| ERROR_CAMERA_ACCESS_DENIED_OR_DISMISSED | 3017 | Oops! It seems like camera access was denied or dismissed. To proceed, kindly grant access through your browser settings. |
| ERROR_MICROPHONE_ACCESS_DENIED_OR_DISMISSED | 3018 | Oops! It seems like microphone access was denied or dismissed. To proceed, kindly grant access through your browser settings. |
| ERROR_CAMERA_PERMISSION_DENIED_BY_OS | 3019 | Camera permission denied by OS system settings. Please check the system settings and grant permission for this browser. |
| ERROR_MICROPHONE_PERMISSION_DENIED_BY_OS | 3020 | Microphone permission denied by OS system settings. Please check the system settings and grant permission for this browser. |
| ERROR_BLUETOOTH_PERMISSION_DENIED | 3090 | Bluetooth permission not granted. To proceed, kindly grant access through your device's settings. |
| Name | Code | Message |
|---|
| ERROR_BLUETOOTH_AUDIO_ROUTE_FAILED | 3010 | Bluetooth audio route failed. SCO connection could not be established after multiple attempts. |
| ERROR_GET_DISPLAY_MEDIA | 3013 | Your browser/Device does not support Screen Sharing. |
| ERROR_CAMERA_NOT_FOUND | 3021 | Please ensure your camera is connected and turned on, and that the camera driver is installed and up-to-date. |
| ERROR_MICROPHONE_NOT_FOUND | 3022 | Please ensure your microphone is connected and turned on. |
| ERROR_CAMERA_IN_USE | 3023 | The camera is being used by another application. Please close any programs utilizing the camera, such as video conferencing tools, screen recording software, or other browsers. Restart your browser and attempt again. |
| ERROR_MICROPHONE_IN_USE | 3024 | The microphone is being used by another application. Please close any programs utilizing the microphone, such as video conferencing tools, screen recording software, or other browsers. Restart your browser and attempt again. |
| ERROR_VIDEO_SOURCE_INITIATION_FAILED | 3026 | Unable to initiate video source. Please verify browser settings for video permissions. |
| ERROR_CAMERA_ACCESS_UNAVAILABLE | 3033 | Camera access unavailable: Please ensure your device is compatible and that you're on a secure website (https://). |
| ERROR_MICROPHONE_ACCESS_UNAVAILABLE | 3034 | Microphone access unavailable: Please ensure your device is compatible and that you're on a secure website (https://). |
| ERROR_NO_WEBCAM_DEVICE_FOUND | 3051 | Whoops! No Webcam Found: We couldn't find your camera. Is it plugged in and turned on? If so, try restarting your computer or checking your device settings. If you need help, check out troubleshooter at https://test.8x8.vc/. Also, ensure you're on a secure website (https://). |
| ERROR_NO_MICROPHONE_DEVICE_FOUND | 3059 | Whoops! No Microphone Found: We couldn't find your microphone. Is it plugged in and turned on? If so, try restarting your computer or checking your device settings. Also, ensure you're on a secure website (https://). |
These errors are triggered when there are issues with video, audio, or screen-share tracks, or when the requested codec is not supported.
| Name | Code | Message |
|---|
| ERROR_WEBCAM_TRACK_ENDED | 3027 | Webcam track has ended or the webcam is disconnected. Please ensure your webcam is properly connected and try restarting it. |
| ERROR_CUSTOM_VIDEO_TRACK_ENDED | 3031 | The provided custom video track is in an ended state. Please verify the video track's status, and try again. |
| ERROR_CUSTOM_AUDIO_TRACK_ENDED | 3032 | The provided custom audio track is in an ended state. Please verify the audio track's status, and try again. |
| ERROR_WEBCAM_PRODUCE_FAILED | 3049 | The camera track was created but could not be published to the room. |
| ERROR_VIDEO_TRACK_CREATION_FAILED | 3053 | Failed to create the video track. |
| ERROR_MICROPHONE_PRODUCE_FAILED | 3058 | The microphone track was created but could not be published to the room. |
| ERROR_AUDIO_TRACK_CREATION_FAILED | 3060 | Failed to create the audio track. |
| ERROR_SCREENSHARE_PRODUCE_FAILED | 3061 | Failed to start screen sharing. |
| ERROR_WEBCAM_NOT_ENABLED | 3062 | The webcam is not enabled. Enable it before setting quality. |
| ERROR_SET_WEBCAM_QUALITY_FAILED | 3063 | Failed to set the webcam quality. |
| ERROR_CAPTURE_IMAGE_FAILED | 3069 | Unable to capture the image. Please try again. |
| ERROR_INVALID_CUSTOM_TRACK_CONFIG | 3071 | Invalid custom track configuration. |
| ERROR_WEBCAM_CLOSE_PRODUCER_FAILED | 3076 | The camera could not be turned off. Please try again. |
| ERROR_MICROPHONE_CLOSE_PRODUCER_FAILED | 3077 | The microphone could not be turned off. Please try again. |
For how VideoSDK handles these errors, refer to the Video Codecs guide.
| Name | Code | Message |
|---|
| ERROR_VIDEO_PRODUCE_CODEC_NOT_SUPPORTED | 3045 | The provided codec is not supported for producing video on this device. Falling back to VP8. |
| ERROR_MULTISTREAM_NOT_SUPPORTED | 3046 | Multistream is not supported for this codec. |
| ERROR_NO_SUPPORTED_VIDEO_CODEC | 3052 | No supported video codec is available on this device. |
| CREATE_CONSUMER_FAILED | 4050 | Failed to create consumer. |
| CODEC_NOT_SUPPORTED | 4051 | Your platform doesn't support the remote participant's video codec. |
These errors are triggered when an action cannot run in the current state — called before the room is joined, after the room has left it, while it is reconnecting, or while the same action is still running. They are also triggered by an invalid argument, or when the server does not answer in time.
| Name | Code | Message |
|---|
| ERROR_ACTION_PERFORMED_BEFORE_ROOM_JOINED | 3035 | Oops! Something went wrong. The room was in a connecting state, and during that time, an action encountered an issue. Please try again after joining a room. |
| ERROR_ACTION_NOT_SUPPORTED_IN_MODE | 3066 | This action is not supported in the current room mode. |
| ERROR_ACTION_NOT_SUPPORTED | 3068 | This action is not supported here. |
| ERROR_INVALID_PARAMETER | 3073 | The provided parameter is missing or invalid. Please verify the provided parameter and try again. |
| Name | Code | Message |
|---|
| ERROR_UNABLE_TO_JOIN_ROOM | 3047 | Unable to join the room. Please try again. |
| ERROR_MEDIA_NOT_READY | 3048 | The room's media connection is not ready yet. Please try again in a moment. |
| ERROR_MEDIA_DEVICE_NOT_INITIALIZED | 3050 | The media device has not been initialized. |
| ERROR_MEDIA_DEVICE_NOT_LOADED | 3064 | The media device is not loaded yet. Please try again in a moment. |
| ERROR_OPERATION_TIMED_OUT | 3079 | The operation timed out. Please check your connection and try again. |
| Name | Code | Message |
|---|
| ERROR_ALREADY_IN_REQUESTED_STATE | 3054 | The requested state is already active. |
| ERROR_OPERATION_IN_PROGRESS | 3055 | The requested operation is already in progress. |
| ERROR_OPERATION_ABORTED | 3056 | The operation was aborted before it completed. |
| ERROR_ROOM_RECONNECTING | 3065 | The room is reconnecting. Please try again once it reconnects. |
These errors are triggered when ending the room fails, or when the server rejects a request that targets a remote participant or changes the room — including stream subscriptions, room mode, room switching, and media relay. The state stays as it was.
| Name | Code | Message |
|---|
| REMOVE_PARTICIPANT_FAILED | 4066 | Failed to remove the participant. Please try again. |
| ENABLE_PARTICIPANT_MIC_FAILED | 4067 | Failed to enable the participant's microphone. Please try again. |
| DISABLE_PARTICIPANT_MIC_FAILED | 4068 | Failed to disable the participant's microphone. Please try again. |
| ENABLE_PARTICIPANT_WEBCAM_FAILED | 4069 | Failed to enable the participant's webcam. Please try again. |
| DISABLE_PARTICIPANT_WEBCAM_FAILED | 4070 | Failed to disable the participant's webcam. Please try again. |
| PIN_FAILED | 4071 | Failed to pin the participant. Please try again. |
| UNPIN_FAILED | 4072 | Failed to unpin the participant. Please try again. |
| SET_QUALITY_FAILED | 4073 | Failed to set the stream quality. Please try again. |
| Name | Code | Message |
|---|
| ERROR_END_ROOM_FAILED | 3057 | Unable to end the room. Please try again. |
| ADAPTIVE_SUBSCRIPTION_NOT_ENABLED_BY_SDK | 4047 | Adaptive subscription is not enabled by the SDK. Please contact at support@videosdk.live |
| ADAPTIVE_SUBSCRIPTION_ENABLE_FAILED | 4048 | Adaptive subscription is already enabled. |
| ADAPTIVE_SUBSCRIPTION_DISABLE_FAILED | 4049 | Adaptive subscription is already disabled. |
| PAUSE_ALL_STREAMS_FAILED | 4057 | Failed to pause all streams. Please try again. |
| RESUME_ALL_STREAMS_FAILED | 4058 | Failed to resume all streams. Please try again. |
| RESPOND_ENTRY_FAILED | 4059 | Failed to respond to the entry request. Please try again. |
| CHANGE_MODE_FAILED | 4065 | Failed to change the room mode. Please try again. |
| PAUSE_STREAM_FAILED | 4074 | Failed to pause the stream. Please try again. |
| RESUME_STREAM_FAILED | 4075 | Failed to resume the stream. Please try again. |
| SWITCH_ROOM_FAILED | 4076 | Failed to switch the room. Please try again. |
| REQUEST_MEDIA_RELAY_FAILED | 4078 | Failed to request media relay. Please try again. |
| STOP_MEDIA_RELAY_FAILED | 4079 | Failed to stop media relay. Please try again. |
| CONSUME_MIC_STREAMS_FAILED | 4080 | Failed to consume the participant's microphone streams. Please try again. |
| CONSUME_WEBCAM_STREAMS_FAILED | 4081 | Failed to consume the participant's webcam streams. Please try again. |
| STOP_CONSUMING_MIC_STREAMS_FAILED | 4082 | Failed to stop consuming the participant's microphone streams. Please try again. |
| STOP_CONSUMING_WEBCAM_STREAMS_FAILED | 4083 | Failed to stop consuming the participant's webcam streams. Please try again. |
| RESPOND_MEDIA_RELAY_REQUEST_FAILED | 4084 | Failed to respond to the media relay request. Please try again. |
These errors are triggered while using in-room collaboration features such as PubSub messaging, data messages, file sharing, the realtime key-value store, the whiteboard, and translation.
| Name | Code | Message |
|---|
| PUBSUB_PUBLISH_FAILED | 4087 | Failed to publish the message to the pubsub topic. Please try again. |
| PUBSUB_SUBSCRIBE_FAILED | 4088 | Failed to subscribe to the pubsub topic. Please try again. |
| PUBSUB_UNSUBSCRIBE_FAILED | 4089 | Failed to unsubscribe from the pubsub topic. Please try again. |
| Name | Code | Message |
|---|
| ERROR_SEND_FAILED | 3070 | Unable to send the message. Please try again. |
| ERROR_PAYLOAD_TOO_LARGE | 3072 | Payload exceeds the maximum allowed size. |
| Name | Code | Message |
|---|
| ERROR_FILE_UPLOAD_FAILED | 3074 | Unable to upload the file. Please try again. |
| ERROR_FILE_FETCH_FAILED | 3075 | Unable to fetch the file. Please try again. |
| Name | Code | Message |
|---|
| FAILED_TO_SET_VALUE | 4045 | Failed to set realtime store value. |
| FAILED_TO_GET_VALUE | 4046 | Failed to get realtime store value. |
| FAILED_TO_OBSERVE_VALUE | 4085 | Failed to start observing the realtime store value. |
| FAILED_TO_STOP_OBSERVING_VALUE | 4086 | Failed to stop observing the realtime store value. |
| Name | Code | Message |
|---|
| START_WHITEBOARD_FAILED | 4054 | Failed to start the whiteboard. Please try again. |
| STOP_WHITEBOARD_FAILED | 4055 | Failed to stop the whiteboard. Please try again. |
| WHITEBOARD_OPERATION_IN_PROGRESS | 4056 | A whiteboard operation is already in progress. Please wait for it to complete. |
| Name | Code | Message |
|---|
| START_TRANSLATION_FAILED | 4042 | Translation start request failed due to an unknown error. |
| STOP_TRANSLATION_FAILED | 4043 | Translation stop request failed due to an unknown error. |
| CHANGE_TRANSLATION_LANGUAGE_FAILED | 4044 | Change translation language request failed due to an unknown error. |
| TRANSLATION_FAILED | 5015 | Translation failed due to an unknown error. |
These errors are reported when the cause of a failure is not known. A failure that the SDK cannot classify reaches your app as UNKNOWN_ERROR, with the original message.
| Name | Code | Message |
|---|
| UNKNOWN_ERROR | 4000 | An unknown error occurred. |
| SOMETHING_WENT_WRONG | 5000 | Something went wrong. |
- The
message you receive can be more specific than the text in these tables, and it can differ between Android and iOS. Check the code, not the message.
- Some codes come from one platform only, for example
3010 and 3090 on Android, and 3020 on iOS.
The API references for all the methods and events utilized in this guide are provided below.
Ask us on discord
