Mobile SDK: errors, causes and fixes

Last updated: 13 October 2026 · 7 min read

Steps

1. 1

   Key and connection errors

   • A log line starting with api_key that says the key is wrong or not for this platform (server 401 invalid_api_key; the SDK writes this line in Azerbaijani). Cause: the key was copied wrong, revoked, more than 7 days have passed since a new one was made, or it is the other platform's key. Fix: the android_… key on Android, the ios_… key on iOS; compare the key's beginning in the Installation section, and make a “New key” if needed.
   • The same error on iOS with a correct key. Cause: the channel's “iOS Bundle ID” differs from the app's Bundle ID, which the iOS SDK sends on every connection. The Bundle ID is entered in the wizard when the channel is created, and the dashboard has no place to change it later. Fix: write the app's correct Bundle ID to Clomni AI, and the Clomni team corrects it.
   • call Clomni.initialize first. Cause: a method was called before initialize. Fix: call initialize at launch, on Android in Application.onCreate, with the class named in the manifest with android:name.
   • initialize was called before; the first call stays. Fix: call it once; restart the app to change the key.
   • this App SDK inbox is switched off in Clomni. Cause: the channel is switched off for the account, or the account is not active. The Messenger does not open. Fix: write to Clomni AI; it checks and, if needed, passes it to the Clomni team.
   • No connection on a company network. Cause: a proxy or an allow list. Fix: allow app.clomni.ai for HTTPS and WebSocket.
2. 2

   Identifying users

   • A log line starting with user_hash that says the hash is wrong (server 403 identity_verification_failed). Cause: the hash does not match. Fix: the hash must be made from exactly the same user_id string as in loginUser, with the current secret, as lower-case hex. Without userId, from the trimmed lower-case e-mail. Security › “Test a hash” names the cause: “It does not match”, “The hash is in upper case”, “The hash must be 64 hex characters”.
   • Logins are refused after the secret was changed. Cause: after “Make a new secret”, the old secret works for only 7 more days. If “Test a hash” says “Correct, but made with the old secret”, the server still uses the old secret. Fix: move the server to the new secret.
   • In “Enforced” mode a login without a hash is refused. Fix: send the hash, or go back to “Recommended” until every app version sends it.
   • The phone's next user sees the previous user's conversations. Cause: logout is not called. Fix: call Clomni.logout() with your app's own logout.
   • The agent does not see the user's name. Fix: pass name and email to loginUser, and use updateUser for later changes.
3. 3

   Push does not arrive

   Start with “Test push” in the channel's Push section: the answer is FCM's or APNs' own, explained in “Mobile SDK push keys”.

   • iOS: BadEnvironmentKeyInToken. Cause: the APNs key is for Sandbox only or Production only. It works from Xcode but not from TestFlight (or the other way round). Fix: create a new key in Apple Developer with “Environment: Sandbox & Production” and upload it.
   • The device is not in the “Test push” list. Cause: the token did not reach Clomni. Fix: allow notifications on the phone, check the setDeviceToken call, open the Messenger once.
   • Android 13+: no notification, notification not shown (POST_NOTIFICATIONS?) in the log. Fix: declare POST_NOTIFICATIONS in the manifest and ask for it. The SDK never asks for it itself.
   • Android: google-services.json was uploaded to the dashboard. The dashboard says “The file has no project_id”. Fix: upload the file from Firebase › Project settings › Service accounts › “Generate new private key”.
   • Android: SENDER_ID_MISMATCH. Cause: the service account is from another Firebase project. Fix: the service account of the same project as the app's google-services.json.
   • Android: notifications arrive only while the app is open. Cause: the data message is handled only on screen. Fix: ClomniPush.handle in a FirebaseMessagingService; in React Native setBackgroundMessageHandler in index.js; in Flutter onBackgroundMessage before runApp; in Unity your own ListenerService.
   • iOS: the capability is missing. Cause: the Push Notifications capability was not added, so no token is issued. Fix: Xcode › Signing & Capabilities › + Capability › Push Notifications.
   • iOS with React Native or Flutter: a tap on a Clomni notification only opens the app, not the conversation. Cause: Clomni iOS pushes come straight from APNs, and the Firebase library does not see them. Fix: a native UNUserNotificationCenterDelegate (ClomniNotifications) and the APNs token through getAPNSToken, as in the platform's article.
   • iOS: InvalidProviderToken (the Key ID or Team ID is wrong), DeviceTokenNotForTopic (the Bundle ID in Push is not the app's).
   • iOS: the app crashes on a tap with “Call must be made on main thread”. Fix: make the delegate methods @MainActor.
   • Android: the icon is a grey square. Fix: a white silhouette icon with setNotificationIcon.
   • Android: the log says push token not registered: …. Cause: the token did not reach the server. Fix: check the network, the setDeviceToken call and the service account JSON in the dashboard.
4. 4

   Installation (Android, iOS, React Native, Flutter, Unity)

   • The Android build stops at the manifest merge: provider#androidx.core.content.FileProvider@authorities … collides with another value (for example with unity-webview in Unity). Cause: SDK 1.0.4 and earlier declared androidx's own FileProvider class, which the app or another library declares too. Fix: update the SDK to 1.0.5 (Unity: #unity-1.0.5, then resolve with EDM4U). If you added tools:replace because of this error, remove it.
   • pod install cannot find ClomniMessenger (“Unable to find a specification”). Cause: the SDK is not on CocoaPods trunk. Fix: pod 'ClomniMessenger', :git => 'https://github.com/clomni/clomni-mobile-sdk.git', :tag => '1.0.4'. In Unity, change this line in the build folder's Podfile after every iOS build.
   • React Native: pod install says “@clomni/react-native needs React Native 0.75 or later”. Fix: update React Native to 0.75+, or add the pod 'ClomniMessenger' line above to the Podfile.
   • React Native: link errors on ClomniMessenger symbols. Fix: the same Podfile line and pod install.
   • React Native, Expo: “The package doesn't seem to be linked”. Cause: Expo Go does not load native modules. Fix: a development build (npx expo prebuild, npx expo run:ios, EAS build).
   • Flutter: pod install stops with “clomni_flutter: the iOS SDK is not on CocoaPods trunk”. Cause: Swift Package Manager is off and the Podfile has no line. Fix: flutter config --enable-swift-package-manager, or write the line inside target 'Runner'.
   • Flutter, Android: the app crashes when the Messenger opens, the floating button does not show. Fix: MainActivity must extend FlutterFragmentActivity.
   • Unity: nothing happens in the Editor, which is normal. Xcode cannot find the module: open the .xcworkspace.
5. 5

   Messenger, flows and language

   • The Messenger does not open and the log is empty. Fix: turn on the debug log; in Unity, test on a device.
   • iOS: no window to present the messenger from yet. Fix: call present after the screen is shown.
   • The Messenger opens but stays empty or shows “Try again”. Cause: the first load failed: no internet, app.clomni.ai is blocked, or the key was refused. Fix: look for the error in the log.
   • A change in the dashboard does not show in the app. Cause: the Appearance is still a draft. Fix: Appearance › “Publish”.
   • startFlow does nothing. Cause: no published flow is tied to the event. Fix: in the flow builder, trigger “App event”, the same name, flow published. The Flows section must show “Event: …”.
   • startFlow was given the flow's name. The event name is not the flow's name: pass the name on the flow's “Event: …” line in the Flows section. A flow with the “When a conversation starts” trigger does not start with startFlow.
   • The new conversation flow does not run. Cause: the flow chosen in the wizard is still a draft, and “Overview” says “The new conversation flow is not published.” Fix: publish it in the Flows section.
   • {{data.…}} stays empty in a flow's text. Fix: the same key name in the startFlow data and in the flow.
   • The Messenger speaks the wrong language. Cause: setLanguage picked a language that is off in the dashboard, or none was picked and the phone's language is not enabled. Fix: turn the language on in Appearance › “Languages” and publish, or call setLanguage("az").
   • The floating button does not show. Cause: it is off both in the dashboard and in code. Fix: setLauncherVisible(true), or Appearance › Theme › “Floating button”.
   • React Native: the floating button does not show on a cold start. Cause: a bug in SDK 1.0.1, fixed in 1.0.2. Until then, open the Messenger from your own button.
   • React Native, Android: the open Messenger disappears when the app is opened again from its icon. Cause: MainActivity is singleTask. Fixed in SDK 1.0.2.
   • The log says setTheme: primaryColor "…" is not #RRGGBB. Cause: the colour's format. Fix: # and six hex digits, for example #0A66C2.
   • iOS: font family "…" is not in the app; the system font stays. Cause: the font is not in the bundle. Fix: add the font file to the target and to UIAppFonts in Info.plist.
   • An agent does not see conversations from the app. Fix: add them in the channel's “Collaborators” section.
   • “Overview”: “… devices run an old SDK version”. Fix: release the app with the new SDK.
6. 6

   Still not working

   Write to Clomni AI with: the platform and SDK version (Clomni.version in Kotlin and Swift), the App ID, what “Overview” says, the debug log from the moment of the problem, and for push the “Test push” answer. Never send the Identity Secret, a full API key, the .p8 file or the service account file.

7. 7

   Full guide

   • PDF: Clomni Mobile SDK guide, in English, Azerbaijani and Russian.
   • Online: Troubleshooting.
   • In the dashboard: “Guide” in the channel's settings column.