Cometchat Flutter Error Handling

CometChat Flutter SDK v5 Error Handling

All CometChat errors arrive as CometChatException in onError callbacks. The exception has three fields: code (String), message (String?), details (String?). Never leave onError empty.

CometChatException Structure

class CometChatException implements Exception {
  String code;      // Machine-readable error code
  String? details;  // Human-readable details
  String? message;  // Additional context
}

Internal SDK uses typed exceptions (AuthException, NetworkException, StateException, ValidationException, NotFoundException) — all converted to CometChatException before reaching your onError callback.

Error Code Reference

Init Errors (SdkErrorCode)

Auth Errors

Validation Errors (ErrorCode)

Notification Errors

Calling Errors

Calling uses two exception types: CometChatException (from Chat SDK signaling) and CometChatCallsException (from Calls SDK WebRTC session).

Error Handling Pattern

CometChat.sendMessage(textMessage,
  onSuccess: (TextMessage message) {
    // Handle success
  },
  onError: (CometChatException e) {
    debugPrint("Error: ${e.code} - ${e.message}");

    // Map to user-friendly message
    final userMessage = _mapErrorToUserMessage(e.code);
    ScaffoldMessenger.of(context).showSnackBar(
      SnackBar(content: Text(userMessage)),
    );
  },
);

Error → User Message Mapping

String mapCometChatError(String code) {
  switch (code) {
    case 'ERR_NOT_INITIALIZED':
      return 'Chat service is starting up. Please wait.';
    case 'ERR_INVALID_APP_ID':
    case 'ERR_INVALID_REGION':
      return 'Chat configuration error. Please contact support.';
    case 'ERR_AUTH_TOKEN_EXPIRED':
      return 'Your session has expired. Please sign in again.';
    case 'ERROR_USER_NOT_LOGGED_IN':
      return 'Please sign in to use chat.';
    case 'ERROR_INVALID_RECEIVER_ID':
      return 'Could not find the recipient.';
    case 'ERROR_REQUEST_IN_PROGRESS':
      return 'Please wait, request is being processed.';
    case 'ERR_INITIALIZATION_FAILED':
      return 'Could not connect to chat. Check your internet connection.';
    default:
      return 'Something went wrong. Please try again.';
  }
}

Retry Pattern with Exponential Backoff

The SDK defines retry constants: max 3 attempts, initial delay 1s, max delay 10s, multiplier 2x.

Future<T> retryWithBackoff<T>({
  required Future<T> Function() operation,
  int maxAttempts = 3,
  Duration initialDelay = const Duration(seconds: 1),
  Set<String> retryableCodes = const {'ERR_INITIALIZATION_FAILED'},
}) async {
  Duration delay = initialDelay;

  for (int attempt = 1; attempt <= maxAttempts; attempt++) {
    try {
      return await operation();
    } on CometChatException catch (e) {
      if (!retryableCodes.contains(e.code) || attempt == maxAttempts) rethrow;
      debugPrint("Attempt $attempt failed (${e.code}). Retrying in ${delay.inSeconds}s...");
      await Future.delayed(delay);
      delay *= 2;
      if (delay > const Duration(seconds: 10)) delay = const Duration(seconds: 10);
    }
  }
  throw StateError('Unreachable');
}

Error Categories for Retry Decisions

Anti-Patterns

Stripping CometChatException in repository/wrapper layers:

// ❌ WRONG — converts typed exception to String, loses error code
// Upstream code can no longer do retry decisions or user-friendly mapping
catch (e) { throw e.toString(); }

// ✅ CORRECT — preserve the typed exception
on CometChatException catch (e) { rethrow; }
catch (e) { throw CometChatException('UNKNOWN', details: e.toString()); }

Empty onError — silently swallowing errors:

// ❌ WRONG
CometChat.sendMessage(msg, onSuccess: (_) {}, onError: (_) {});

// ✅ CORRECT — always log and handle
CometChat.sendMessage(msg,
  onSuccess: (_) {},
  onError: (e) {
    debugPrint("Send failed: ${e.code}");
    showUserFriendlyError(e);
  },
);

Retrying non-retryable errors:

// ❌ WRONG — retrying a validation error loops forever
while (true) {
  try { await sendMessage(msg); break; }
  catch (e) { await Future.delayed(Duration(seconds: 1)); }
}

// ✅ CORRECT — only retry network errors
if (e.code == 'ERR_INITIALIZATION_FAILED') { retry(); }
else { showError(e); }

Catching generic Exception instead of CometChatException:

// ❌ WRONG — loses error code information
try { await operation(); }
catch (e) { print(e.toString()); }

// ✅ CORRECT — preserve the typed exception
try { await operation(); }
on CometChatException catch (e) { handleCometChatError(e); }
catch (e) { handleUnexpectedError(e); }

Checklist

• Every onError callback logs the error code and surfaces a user-friendly message
• Error codes mapped to user-friendly strings (not raw codes shown to users)
• Retry logic only for network/transient errors, not validation/config errors
• CometChatException caught specifically (not generic Exception)
• ERR_AUTH_TOKEN_EXPIRED triggers re-authentication flow, not retry
• ERROR_REQUEST_IN_PROGRESS handled by waiting, not retrying immediately