Error Codes - CometChat Docs

AI Integration Quick Reference

let uid = "UID";
let authKey = "AUTH_KEY";

// All errors are CometChatException objects
try {
  await CometChat.login(uid, authKey);
} catch (error) {
  console.log(error.code);    // e.g., "AUTH_ERR_AUTH_TOKEN_NOT_FOUND"
  console.log(error.name);    // e.g., "AUTH_ERR_AUTH_TOKEN_NOT_FOUND"
  console.log(error.message); // Human-readable description
  console.log(error.details); // Additional context (if available)
}

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

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

Property	Type	Description
`code`	`string \| number`	Machine-readable error code
`name`	`string`	Error name (often matches code)
`message`	`string`	Human-readable description
`details`	`string`	Additional context or troubleshooting info

TypeScript
JavaScript

try {
  const user: CometChat.User = await CometChat.login(authToken);
} catch (error: CometChat.CometChatException) {
  switch (error.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:
      console.error("Unexpected error:", error.message);
  }
}

try {
  const user = await CometChat.login(authToken);
} catch (error) {
  switch (error.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:
      console.error("Unexpected error:", error.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.

Media Upload Errors

Raised by the Upload Files flow — delivered through the MediaUploadListener (onFileError / onFileFailure) — and by sendMediaMessage(). Rejected errors (onFileError) mean the input must change and are not retryable; failed errors (onFileFailure) are transient and can be retried with retryFileUpload().

Code	Surfaced via	Retryable	Message
`ERR_INVALID_FILE_OBJECT`	`onFileError`	No	The provided file is invalid or its size cannot be determined.
`ERR_FILE_SIZE_EXCEEDED`	`onFileError`	No	The file `%s` exceeds the maximum allowed size of `%s` bytes.
`ERR_PERMISSION_DENIED`	`onFileError`	No	The sender does not have permission to upload media to the specified `receiverId` / `receiverType` (role/scope-based access control).
`ERR_FILE_COUNT_EXCEEDED`	`sendMediaMessage()`	No	The number of attachments exceeds the allowed limit of `%s`.
`ERR_S3_UPLOAD_FAILED`	`onFileFailure`, `onFileError`	Yes / No	Failed to upload the file to storage (`onFileFailure`, retryable); also the fallback when the server declines a file with no specific code (`onFileError`, not retryable).
`ERR_PRESIGNED_URL_EXPIRED`	`onFileFailure`	Yes	The pre-signed upload URL has expired. Please retry the upload.
`ERR_UPLOAD_STALLED`	`onFileFailure`	Yes	The upload stalled with no progress and was aborted.
`ERR_UPLOAD_CANCELLED`	—	—	The upload was cancelled.

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.
`ERR_CONVERSATION_NOT_ACCESSIBLE`	The conversation is not accessible to the requesting user.

ERR_CONVERSATION_NOT_ACCESSIBLE is the normal, expected response when no conversation exists yet between the two users — not just when a user tries to open a conversation with themselves. A one-to-one conversation only becomes accessible once at least one message has been exchanged (a user can access their own one-to-one conversations, and group conversations they are a member of).To create the conversation so it can be fetched, use one of these approaches:

Send and delete a message between the two users to instantiate the conversation, or
Use the Add Friends API with addToConversations: true so the conversation is created when the friendship is established.

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.

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

​Media Upload Errors

​User Errors

​Group Errors

​Conversation Errors

​Receipt Errors

​AI Feature Errors

​Extension Errors

​Feature Restriction Errors

​Network & API Errors

​Validation Errors

​Prosody (WebSocket Server) Errors

​General Errors

​Server-Side API Errors

​Next Steps