Error Codes

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

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

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);
  }
}

JavaScript

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.

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.

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