---
schema_version: "1"
id: a62ef6bd5209b71b37836bc65a1910f286a6e9d3756912269bbdb1fb1f2cecfa
title: Error Handling Reference - React Native
collection: developer
version: current
locale: en-us
portal_url: https://docs.salesforce.com/developer/current/en-us/genai/agentforce-mobile-sdk/references/react-native/error-handling-overview-react-native.md
canonical_url: https://developer.salesforce.com/docs/ai/agentforce-mobile-sdk/references/agentforce-mobile-sdk/error-handling-overview-react-native.html
source_site: developer.salesforce.com
content_type: documentation
content_hash: 34471385ac2c75ced0fca78ec25d4d12f7425a5720d045e6b04c2240070613b2
products:
  - Agentforce Mobile SDK
  - Agentforce and Einstein Generative AI
---
# 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:

```tsx
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

```tsx
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

```tsx
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

```tsx
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

- [Troubleshooting Guide](/docs/ai/agentforce-mobile-sdk/guide/react-native/agentforce-mobile-sdk-react-native-troubleshooting)
- [Configuration Reference](https://developer.salesforce.com/docs/ai/agentforce-mobile-sdk/references/agentforce-mobile-sdk/configuration-overview-react-native.md)