Error Codes - CometChat Docs

AI Integration Quick Reference

String uid = "UID";
String authKey = "AUTH_KEY";

// All errors are CometChatException objects
try {
  User? user = await CometChat.login(uid, authKey: authKey);
} on CometChatException catch (e) {
  debugPrint(e.code);     // e.g., "AUTH_ERR_AUTH_TOKEN_NOT_FOUND"
  debugPrint(e.message);  // Human-readable description
  debugPrint(e.details);  // Additional context (if available)
}

Error categories: Initialization, Login, Calling, Messages, Groups, Users, Conversations, Receipts, AI, Extensions

Every error thrown by the CometChat SDK is a CometChatException object with three properties:

Property	Type	Description
`code`	`String`	Machine-readable error code
`message`	`String?`	Human-readable description
`details`	`String?`	Additional context or troubleshooting info

try {
  User? user = await CometChat.login(authToken);
} on CometChatException catch (e) {
  switch (e.code) {
    case "AUTH_ERR_AUTH_TOKEN_NOT_FOUND":
      // Token is invalid or expired — prompt re-login
      break;
    case "MISSING_PARAMETERS":
      // A required parameter was not provided
      break;
    default:
      debugPrint("Unexpected error: ${e.message}");
  }
}

Initialization Errors

Code	Message
`MISSING_PARAMETERS`	AppID cannot be empty. Please specify a valid appID.

Code	Message
`COMETCHAT_INITIALIZATION_NOT_DONE`	Please initialize CometChat before using the login method.
`USER_NOT_AUTHORISED`	The authToken of the user is not authorised. Please verify again.
`AUTH_ERR_AUTH_TOKEN_NOT_FOUND`	The auth token does not exist. Please make sure you are logged in and have a valid auth token.
`LOGIN_IN_PROGRESS`	Please wait until the previous login request ends.
`WS_CONNECTION_FAIL`	WebSocket connection failed.
`WS_CONNECTION_FALLBACK_FAIL`	WebSocket connection fallback failed.
`WS_AUTH_FAIL`	WebSocket username/password not correct.
`NO_INTERNET_CONNECTION`	You do not have an internet connection.
`USER_NOT_LOGGED_IN`	Please log in to CometChat before calling this method.

Calling Errors

Code	Message
`CALL_ALREADY_INITIATED`	There is already a call in progress.
`CALL_IN_PROGRESS`	There is already a call in progress.
`NOT_INITIALIZED`	Please call CometChat.init() before calling any other methods.
`NOT_LOGGED_IN`	Please login before starting a call.
`SESSION_ID_REQUIRED`	Please make sure you are passing a correct session ID.
`CALL_SETTINGS_REQUIRED`	Please make sure you are passing the call settings object.
`JWT_NOT_FOUND`	There was an issue while fetching JWT from API.

Message Errors

Code	Message
`INVALID_RECEIVER_TYPE`	Receiver type can be `user` or `group`.
`REQUEST_IN_PROGRESS`	Request in progress.
`NOT_ENOUGH_PARAMETERS`	Timestamp, MessageId, or updatedAfter is required to use fetchNext().
`INVALID_REASON_ID`	Invalid reasonId provided.

User Errors

Code	Message
`INVALID_STATUS_VALUE`	The status parameter accepts only `online` or `offline`.
`INVALID_DIRECTION_VALUE`	The direction parameter accepts only `both`, `blockedByMe`, or `hasBlockedMe`.
`EMPTY_USERS_LIST`	The users list needs to have at least one UID.

Group Errors

Code	Message
`NOT_A_GROUP`	Please use the Group class to construct a new group.
`INVALID_SCOPE_VALUE`	Scope can be `admin`, `moderator`, or `participant`.
`INVALID_GROUP_TYPE`	Group type can be `public`, `private`, `protected`, or `password`.
`ERR_EMPTY_GROUP_PASS`	Password is mandatory to join a group.

Conversation Errors

Code	Message
`INVALID_CONVERSATION_TYPE`	Conversation type can be `user` or `group`.
`CONVERSATION_NOT_FOUND`	Conversation not found. Check the value of conversationWith and conversationType.

Receipt Errors

Code	Message
`MISSING_PARAMETERS`	Expected 4 parameters, received 3.
`NO_WEBSOCKET_CONNECTION`	Connection to WebSocket server is broken. Please retry after some time.
`RECEIPTS_TEMPORARILY_BLOCKED`	Due to high load, receipts have been blocked for your app.
`UNKNOWN_ERROR_OCCURRED`	Unknown error occurred while marking a message as read.

AI Feature Errors

Code	Message
`NO_CONVERSATION_STARTER`	Unable to get conversation starter for this conversation.
`NO_SMART_REPLY`	Unable to get smart reply for this conversation.
`NO_CONVERSATION_SUMMARY`	Unable to get summary of the conversation.
`EMPTY_RESPONSE`	Unable to get a suggestion.
`ERROR_INVALID_AI_FEATURE`	The provided AI Feature cannot be null or empty.

Extension Errors

Code	Message
`ERROR_INVALID_EXTENSION`	The provided extension cannot be null or empty.
`ERROR_EXTENSION_NOT_FOUND`	The provided extension could not be found.

Feature Restriction Errors

Code	Message
`ERROR_INVALID_FEATURE`	The provided feature cannot be null or empty.
`ERROR_FEATURE_NOT_FOUND`	The provided feature could not be found.

Notification Errors

Code	Message
`INVALID_PUSH_PLATFORM`	An invalid Push Platform was detected. Please submit a valid push platform to proceed.
`INVALID_FCM_TOKEN`	An invalid FCM token was detected. Please submit a valid token to proceed.
`INVALID_APNS_DEVICE_TOKEN`	An invalid APNs Device token was detected. Please submit a valid token to proceed.
`INVALID_APNS_VOIP_TOKEN`	An invalid APNs VoIP token was detected. Please submit a valid token to proceed.

Network & API Errors

Code	Message
`FAILED_TO_FETCH`	There is an unknown issue with the API request. Check your internet connection.
`TOO_MANY_REQUEST`	Too many requests. Wait before sending the next request.
`ERR_TOO_MANY_REQUESTS`	Rate limiting. See Rate Limits.

Validation Errors

These errors use dynamic codes based on the parameter name (e.g., INVALID_UID, UID_IS_COMPULSORY):

Pattern	Message
`INVALID_{param}`	The parameter should be a string / number / boolean / object / array.
`{param}_IS_COMPULSORY`	The parameter cannot be blank. Please provide a valid value.
`{param}_NOT_PROVIDED`	Please provide the required parameter.
`ERROR_{param}_EXCEEDED`	Limit exceeded max limit.
`INVALID_SEARCH_KEYWORD`	Invalid search keyword. Please provide a valid search keyword.
`MISSING_KEY`	The key is missing from the object.

Prosody (WebSocket Server) Errors

Code	Message
`ERROR_INVALID_SESSIONID`	The provided sessionId cannot be null or empty.
`ERROR_INVALID_TYPE`	The provided type cannot be null or empty.
`ERROR_INVALID_GROUPLIST`	Grouplist cannot be null or empty.

General Errors

Code	Message
`ERROR_IO_EXCEPTION`	I/O exception occurred.
`ERROR_JSON_EXCEPTION`	JSON parsing exception.
`ERROR_PASSWORD_MISSING`	Password is mandatory for a password group.
`ERROR_LIMIT_EXCEEDED`	Limit exceeded max limit.
`ERROR_INVALID_GUID`	Please provide a valid GUID.
`ERR_SETTINGS_HASH_OUTDATED`	Settings hash is outdated.
`ERR_NO_AUTH`	No authentication credentials found.

Server-Side API Errors

For REST API error codes (returned by the CometChat backend), see the Error Guide. Common server-side errors you may encounter in SDK responses:

Code	Description
`AUTH_ERR_EMPTY_APPID`	Empty App ID in headers
`AUTH_ERR_INVALID_APPID`	Invalid App ID or does not exist in region
`ERR_UID_NOT_FOUND`	User does not exist or is soft deleted
`ERR_GUID_NOT_FOUND`	Group does not exist
`ERR_NOT_A_MEMBER`	User is not a member of the group
`ERR_ALREADY_JOINED`	User has already joined the group
`ERR_MESSAGE_ID_NOT_FOUND`	Message does not exist
`ERR_PLAN_RESTRICTION`	Feature not available with current plan
`ERR_TOO_MANY_REQUESTS`	Rate limit exceeded

See the full list in the Error Guide.

Next Steps

Troubleshooting

Common issues and solutions

Rate Limits

Understand and handle rate limits

Error Guide (REST API)

Complete server-side error code reference

Best Practices

Recommended patterns for error handling

​Initialization Errors

​Login & Authentication Errors

​Calling Errors

​Message Errors

​User Errors

​Group Errors

​Conversation Errors

​Receipt Errors

​AI Feature Errors

​Extension Errors

​Feature Restriction Errors

​Notification Errors

​Network & API Errors

​Validation Errors

​Prosody (WebSocket Server) Errors

​General Errors

​Server-Side API Errors

​Next Steps