--- schema_version: "1" id: db706487de6a7ac13e870a0955b317523ad477f57548163dd39b6f2acc09a472 title: Troubleshoot the React Native SDK collection: developer version: current locale: en-us portal_url: https://docs.salesforce.com/developer/current/en-us/genai/agentforce-mobile-sdk/guides/react-native/agentforce-mobile-sdk-react-native-troubleshooting.md canonical_url: https://developer.salesforce.com/docs/ai/agentforce-mobile-sdk/guide/agentforce-mobile-sdk-react-native-troubleshooting.html source_site: developer.salesforce.com content_type: documentation content_hash: ef1606e3d23991a75eb6dec0b555a2852b9a05b618513d3a4268835a6362482a products: - Agentforce Mobile SDK - Agentforce and Einstein Generative AI --- # 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: ```ruby 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`: ```kotlin override fun getPackages(): List = listOf( MainReactPackage(), AgentforcePackage(), ) ``` 2. Verify the library module is included in `settings.gradle` 3. Clean build: `cd android && ./gradlew clean` **Both platforms - Metro cache:** ```bash 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: ```tsx 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: ```tsx 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: ```xml ``` 4. **Configuration error**: The SDK may have silently failed. Register a logger delegate before launching to capture any error messages: ```tsx 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: ```tsx 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`: ```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`: ```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`: ```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: ```tsx // 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: ```tsx 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: ```tsx 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 - [Requirements](https://developer.salesforce.com/docs/ai/agentforce-mobile-sdk/guide/agentforce-mobile-sdk-react-native-requirements.md) - [Install the SDK](https://developer.salesforce.com/docs/ai/agentforce-mobile-sdk/guide/agentforce-mobile-sdk-react-native-install.md) - [Limitations](https://developer.salesforce.com/docs/ai/agentforce-mobile-sdk/guide/agentforce-mobile-sdk-react-native-limitations.md)