Troubleshoot the React Native SDK

Find solutions to common issues when working with the Agentforce Mobile SDK for React Native.

The native module error indicates that the bridge isn’t properly linked to your app.

1Error: Cannot read property 'configure' of undefined

Or at runtime:

1Invariant Violation: TurboModuleRegistry.getEnforcing(...): 'AgentforceModule' could not be found.

iOS - Pod not installed or linked:

1. Verify the pod is in your Podfile:
   1pod 'ReactNativeAgentforce', :path => '../node_modules/@salesforce/react-native-agentforce/ios'

2. Run cd ios && pod install
3. Open the .xcworkspace (not .xcodeproj)
4. Clean build: Product > Clean Build Folder (Cmd+Shift+K)

Android - Package not registered:

1. Verify AgentforcePackage() is added in MainApplication:
   1override fun getPackages(): List<ReactPackage> = listOf(
   2    MainReactPackage(),
   3    AgentforcePackage(),
   4)

2. Verify the library module is included in settings.gradle
3. Clean build: cd android && ./gradlew clean

Both platforms - Metro cache:

1npx react-native start --reset-cache

These errors occur when the configuration passed to configure() is invalid or incomplete.

1Error: Missing 'type' field (must be 'service' or 'employee')

Solution: Add type: 'service' or type: 'employee' to your config:

1await AgentforceService.configure({
2  type: "service", // Add this
3  serviceApiURL: "...",
4  organizationId: "...",
5  esDeveloperName: "...",
6});

1Error: Start session failed

Cause: The serviceApiURL is incorrect.

Solution:

1. Check that the URL is the Service API endpoint, not your org’s login URL.
2. Common mistake: using https://myorg.my.salesforce.com instead of https://myorg-support.my.salesforce-scrt.com.
3. Verify the URL in Setup > Embedded Service Deployments > your deployment > Settings.
4. Ensure the URL starts with https://.

Cause: Server-side issue in the Salesforce org.

Solution:

1. Verify the agent is active in your org.
2. Check that your org’s Agentforce entitlement is active.
3. Verify the esDeveloperName matches exactly (case-sensitive).

These errors occur when attempting to launch a conversation.

1Error: Agent not configured. Call configure() first.

Solution: Always call configure() first and await its result:

1await AgentforceService.configure({
2  /* ... */
3});
4await AgentforceService.launchConversation();

1Error: Activity not available

Cause: No current React Activity is available.

Solution: Only call launchConversation() when the app is in the foreground with an active Activity. Call it from a button press handler, not from a background task.

If the conversation opens but shows a loading spinner indefinitely:

Possible causes and solutions:

1. Network connectivity: Verify the device has internet access and can reach Salesforce servers.

2. Agent not active: Verify the agent is active and deployed in your Salesforce org. Check Setup > Agentforce to confirm the agent status.

3. Missing AndroidManifest entry (Android only): Verify AgentforceConversationActivity is declared:

   1<activity
   2    android:name="com.salesforce.android.reactagentforce.AgentforceConversationActivity"
   3    android:theme="@style/Theme.AppCompat.Light.NoActionBar"
   4    android:windowSoftInputMode="adjustResize" />

4. Configuration error: The SDK may have silently failed. Register a logger delegate before launching to capture any error messages:

   1AgentforceService.setLoggerDelegate({
   2  onLog(level, message, error) {
   3    console.log(`[${level}] ${message}`, error || "");
   4  },
   5});

5. Wrong serviceApiURL: A 400 error during session start often indicates an incorrect URL. Double-check that you’re using the Service API URL, not your org’s login URL.

These errors relate to OAuth authentication for Employee Agent mode.

Symptom: Conversation fails to load or shows an auth error after working previously.

Solution (with Mobile SDK):

1. Call refreshEmployeeAgentCredentials() explicitly.
2. If refresh fails, call logoutEmployeeAgent() and loginForEmployeeAgent() to re-authenticate.

Solution (direct token): Obtain a new token from your auth system and call configure() again.

1Error: Salesforce SDK not initialized

Cause: The Mobile SDK’s SalesforceSDKManager wasn’t initialized.

Solution: Initialize the Mobile SDK in your Application class before any React Native bridge calls.

isEmployeeAgentAuthSupported() returns false.

Cause: Mobile SDK isn’t included in the build.

Solution:

• iOS: Use pod 'ReactNativeAgentforce/WithMobileSDK'
• Android: Add implementation "com.salesforce.mobilesdk:SalesforceReact:13.1.1"

These issues affect the logger delegate functionality.

Possible causes:

1. Delegate set after configure(): Register the logger before configure() to catch initialization logs.
2. Native module not found: Check for the warning about native module not available.
3. Platform-specific: On Android, the debug log level isn’t emitted.

Cause: Feature flags are read at configure() time.

Solution: After changing flags via setFeatureFlags(), call configure() again:

1await AgentforceService.setFeatureFlags({
2  enableMultiModalInput: true,
3});
4
5// Must reconfigure for changes to take effect
6await AgentforceService.configure({
7  /* same config as before */
8});

These errors occur during the build process on iOS or Android.

1No such module 'AgentforceSDK'

Solution:

1. Run pod install in the ios directory.
2. Ensure you’re using use_frameworks! :linkage => :static.
3. Verify the AgentforceSDK pod is resolved in Podfile.lock.
4. Clean DerivedData: rm -rf ~/Library/Developer/Xcode/DerivedData

1Could not resolve com.salesforce.android.agentforcesdk:agentforce-sdk

Solution: Add the Maven repositories to your app-level build.gradle:

1repositories {
2    maven { url 'https://opensource.salesforce.com/AgentforceMobileSDK-Android/agentforce-sdk-repository' }
3    maven { url 'https://s3.amazonaws.com/inapp.salesforce.com/public/android' }
4}

1Error: coreLibraryDesugaringEnabled is not set

Solution: Add to your android/app/build.gradle:

1android {
2    compileOptions {
3        coreLibraryDesugaringEnabled true
4    }
5}
6
7dependencies {
8    coreLibraryDesugaring "com.android.tools:desugar_jdk_libs:2.1.5"
9}

Symptom: Build errors related to Jetpack Compose version conflicts.

Cause: Your app uses a different Compose BOM version than the bridge.

Solution: Align the Compose BOM version. The bridge uses compose-bom:2024.02.00. If your app uses a different BOM, you may need to exclude the bridge’s BOM and rely on your app’s, or align versions.

Symptom: Build errors related to Kotlin version incompatibility.

Cause: The bridge uses Kotlin 2.2.0. Your app may use a different version.

Solution: Align the Kotlin version in your project-level build.gradle:

1buildscript {
2    ext.kotlin_version = '2.2.0'
3}

Symptom: Swift bridging errors when your app is Objective-C only.

Cause: The bridge is written in Swift, and your Objective-C project needs a bridging header.

Solution:

1. Create an empty Swift file in your Xcode project.
2. When Xcode prompts to create a bridging header, accept.
3. Build again.

Symptom: Logger delegate stops receiving log messages after working initially.

Cause: The logger delegate was cleared, either by calling clearLoggerDelegate(), destroy(), or by a React component unmounting that set up the delegate.

Solution: Ensure your delegate setup persists for the lifetime you need it:

1// Set up at app level, not in a component that might unmount
2AgentforceService.setLoggerDelegate({ onLog: handleLog });

If using a component, ensure the cleanup only happens when appropriate:

1React.useEffect(() => {
2  AgentforceService.setLoggerDelegate({ onLog: handleLog });
3  return () => {
4    // Only clear if this component should own the delegate
5    AgentforceService.clearLoggerDelegate();
6  };
7}, []);

These errors occur when setting additional context variables.

1Error: No active conversation. Launch conversation first, then set context.

Solution: Always launch first:

1await AgentforceService.launchConversation();
2await AgentforceService.setAdditionalContext({ variables: [...] });

1Error: Invalid context variable at index 0: unknown type "text"

Cause: Type names are case-sensitive.

Solution: Use exact casing: 'Text' not 'text', 'Boolean' not 'boolean'.

• Requirements
• Install the SDK
• Limitations

j

Integrate Agentforce with Your Mobile App

Overview

Before You Begin

Custom Lightning Types on Mobile

iOS Quick Start

Android Quick Start

React Native Quick Start

iOS Integration Guide

Android Integration Guide

React Native Integration Guide

Requirements

Install the SDK

Configure the SDK

Conversations

Delegates

Set Up Agentforce Voice

Employee Agent Authentication

Examples

Limitations

Troubleshooting

Release Notes