Error Codes

Complete reference for CometChat Flutter SDK error codes, including client-side validation errors, server-side API errors, and how to handle them.

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.

Login & Authentication Errors

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