Salesforce Docs Portal

Error Handling Reference - React Native

Reference documentation for error handling in the Agentforce Mobile SDK for React Native.

Overview

Errors are thrown as JavaScript Error objects with a code property. Catch them in Promise rejections:

try {
  await AgentforceService.configure(config);
} catch (error) {
  console.log(error.code); // e.g. 'INVALID_CONFIG'
  console.log(error.message); // Human-readable description
}

AgentforceModule Error Codes

Code Source Description
INVALID_CONFIG configure, registerViewProvider Missing or invalid configuration fields. Missing type field, invalid type value, missing required fields, or empty componentMap.
CONFIG_ERROR configure Configuration failed at the native SDK level (for example, network error, invalid credentials).
NOT_CONFIGURED launchConversation, startNewConversation configure() was not called before attempting to launch.
LAUNCH_ERROR launchConversation (iOS) Failed to start the conversation session. Often indicates wrong serviceApiURL (400) or server error (500).
START_NEW_ERROR startNewConversation (iOS) Failed to start a new conversation.
ERROR launchConversation, startNewConversation (Android) General Android error (Activity not available, initialization failure).
INVALID_CONTEXT setAdditionalContext Missing variables array or a variable lacks name/type.
NO_CONVERSATION setAdditionalContext No active conversation. Must call launchConversation() first.
CONTEXT_ERROR setAdditionalContext The native SDK rejected the context.
INVALID_FIELDS registerHiddenPreChatFields (iOS) Fields are not a valid string-to-string map.

EmployeeAgentAuthBridge Error Codes

Code Source Description
NO_ACTIVITY login, refreshAuthCredentials (Android) No current Activity available.
NOT_AVAILABLE login, refreshAuthCredentials (Android) Salesforce SDK not initialized.
LOGIN_FAILED login (Android) No credentials obtained after login flow.
REFRESH_FAILED refreshAuthCredentials (Android) No credentials available after refresh.
ERROR Various (Android) General error with message.

Handling Configuration Errors

try {
  await AgentforceService.configure({
    type: "service",
    serviceApiURL: url,
    organizationId: orgId,
    esDeveloperName: devName,
  });
} catch (error) {
  switch (error.code) {
    case "INVALID_CONFIG":
      console.error("Configuration is invalid:", error.message);
      break;
    case "CONFIG_ERROR":
      console.error("SDK configuration failed:", error.message);
      break;
    default:
      console.error("Unknown error:", error);
  }
}

Handling Launch Errors

try {
  await AgentforceService.launchConversation();
} catch (error) {
  switch (error.code) {
    case "NOT_CONFIGURED":
      console.error("Call configure() first");
      break;
    case "LAUNCH_ERROR":
      // iOS-specific: session start failed
      console.error("Session failed - check serviceApiURL");
      break;
    case "ERROR":
      // Android-specific: general error
      console.error("Launch failed:", error.message);
      break;
    default:
      console.error("Unknown error:", error);
  }
}

Handling Context Errors

try {
  await AgentforceService.setAdditionalContext({
    variables: [{ name: "userId", type: "Text", value: "123" }],
  });
} catch (error) {
  switch (error.code) {
    case "INVALID_CONTEXT":
      console.error("Context format is invalid");
      break;
    case "NO_CONVERSATION":
      console.error("Launch conversation first");
      break;
    case "CONTEXT_ERROR":
      console.error("SDK rejected the context");
      break;
  }
}

Context Variable Validation

The bridge performs client-side validation before sending to native:

  1. The context object must have a variables array.
  2. Each variable must have a non-empty name (string) and type (string).
  3. The type must be one of: Text, Number, Boolean, Date, DateTime, Json, List, Money, Object, Ref, Variable.

If validation fails, a synchronous Error is thrown before the native call.

Platform Error Differences

Method iOS Error Code Android Error Code
launchConversation failure LAUNCH_ERROR ERROR
startNewConversation failure START_NEW_ERROR ERROR
Invalid hidden prechat fields INVALID_FIELDS (not validated)

See Also