Salesforce Docs Portal

Troubleshoot the React Native SDK

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

Native Module Not Found

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

Symptom

Error: Cannot read property 'configure' of undefined

Or at runtime:

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

Solutions

iOS - Pod not installed or linked:

  1. Verify the pod is in your Podfile: 
    pod '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: 
    override fun getPackages(): List<ReactPackage> = listOf(    MainReactPackage(),    AgentforcePackage(),)
  2. Verify the library module is included in settings.gradle
  3. Clean build: cd android && ./gradlew clean

Both platforms - Metro cache:

npx react-native start --reset-cache

Configuration Errors

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

INVALID_CONFIG: Missing 'type' field

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

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

await AgentforceService.configure({
  type: "service", // Add this
  serviceApiURL: "...",
  organizationId: "...",
  esDeveloperName: "...",
});

CONFIG_ERROR: 400 from serviceApiURL

Error: 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://.

CONFIG_ERROR: 500 from server

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).

Conversation Not Launching

These errors occur when attempting to launch a conversation.

NOT_CONFIGURED

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

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

await AgentforceService.configure({
  /* ... */
});
await AgentforceService.launchConversation();

ERROR: Activity not available (Android)

Error: 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.

Blank or Loading Screen

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:

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

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

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

  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.

Employee Agent Token Issues

These errors relate to OAuth authentication for Employee Agent mode.

Token Expired

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.

Login Flow Not Appearing (Android)

Error: 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.

Employee Agent Auth Not Supported

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"

Log Forwarding Not Working

These issues affect the logger delegate functionality.

No Logs Received

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.

Feature Flag Changes Not Taking Effect

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

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

await AgentforceService.setFeatureFlags({
  enableMultiModalInput: true,
});

// Must reconfigure for changes to take effect
await AgentforceService.configure({
  /* same config as before */
});

Platform-Specific Build Errors

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

iOS: Module 'AgentforceSDK' Not Found

No 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

Android: Maven Repository Not Found

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

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

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

Android: Desugaring Error

Error: coreLibraryDesugaringEnabled is not set

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

android {
    compileOptions {
        coreLibraryDesugaringEnabled true
    }
}

dependencies {
    coreLibraryDesugaring "com.android.tools:desugar_jdk_libs:2.1.5"
}

Android: Compose Version Conflict

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.

Android: Kotlin Version Mismatch

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:

buildscript {
    ext.kotlin_version = '2.2.0'
}

iOS: Bridging Header Issues

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.

Logs Stop After a While

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:

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

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

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

Additional Context Errors

These errors occur when setting additional context variables.

NO_CONVERSATION

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

Solution: Always launch first:

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

Invalid Type

Error: 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'.

See Also