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.

Or at runtime:

iOS - Pod not installed or linked:

  1. Verify the pod is in your Podfile:
  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:
  2. Verify the library module is included in settings.gradle
  3. Clean build: cd android && ./gradlew clean

Both platforms - Metro cache:

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

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

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.

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

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:

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

  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.

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:

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

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

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

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

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:

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:

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

These errors occur when setting additional context variables.

Solution: Always launch first:

Cause: Type names are case-sensitive.

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