Troubleshooting

Organized by what you see. Many of these failures are silent, so the symptom is often "nothing happens".

Every lookup returns nothing

Test with a number you know. Look up +18883578668, which is CallerAPI LC. Most phone numbers do not belong to a business, so an empty answer for a random number is correct behavior.

If the known number also returns nothing, your credentials are not reaching the SDK.

On Android, read the log. Filter Logcat for CallerAPI. The line native init failed means the SDK started with no usable credentials, gave up, and turned itself off. Nothing else reports this.

Check where your credentials live. The three meta-data entries must sit inside <application>, next to your activities. Outside it, the build still succeeds and the SDK finds nothing.

On iOS, check for error code -2. Catch the error and print the code. Code -2 means the server refused your credentials.

Check the app identity. The server refuses a credential presented by an app it was not issued to. Your applicationId on Android, or your bundle identifier on iOS, must match the app you created in the dashboard.

The app crashes with "CallerAPI not initialised"

You called a lookup before register, on Android.

Confirm your <application> tag has android:name=".App", and that the class name matches your file. A common cause is creating the Application subclass and forgetting the manifest attribute.

"CallerAPI native module is not available", React Native

The native side is not linked. A Metro reload cannot fix this, because native code needs a full build.

If it persists, delete node_modules and ios/Pods, then install again.

"CallerAPI.lookupLabel is not a function", React Native

You used a named import. Change it:

import CallerAPI from '@callerapi/react-native';        // correct
import { CallerAPI } from '@callerapi/react-native';    // wrong

It works on Android and not on iOS, Flutter or React Native

You did not add the iOS credentials, or you did not run pod install after adding them.

Add these to ios/Runner/Info.plist for Flutter, or ios/YourApp/Info.plist for React Native:

<key>CallerAPISDKKey</key>
<string>your-sdk-key</string>
<key>CallerAPISDKSecret</key>
<string>your-sdk-secret</string>

Then run pod install and rebuild.

The Android build fails

Gradle errors about Java or Kotlin versions. Use JDK 17. Check with java -version, and in Android Studio under Settings > Build > Build Tools > Gradle.

minSdkVersion 21 cannot be smaller than 24. Raise minSdk to 24 in app/build.gradle.kts.

Duplicate class or duplicate manifest entry for CallerScreeningService. You declared the service yourself. Remove it. The SDK merges it in.

The iOS build fails

Cannot find CallerAPIConfig in scope. Add import CallerAPI. Both CallerAPI and CallerAPIConfig live in that module, not in CallerAPILiveCallerID.

Cannot find CallerAPILiveCallerID in scope, in your extension. Add import CallerAPILiveCallerID, and add the library to the extension target's Frameworks and Libraries. Adding it to your app target is not enough.

The Flutter iOS build fails after adding the package. On Flutter 3.44 and later, run flutter config --no-enable-swift-package-manager. The plugin ships a CocoaPods podspec.

The dashboard shows zero devices while lookups work

On Android, you are missing com.callerapi.sdk.CLIENT_KEY. Lookups need only the key and secret. Device counting needs the client key as well.

On iOS with Live Caller ID, you did not call bootstrap with your lcidClientKey.

Android: nothing happens on incoming calls

The call screening role is not held. This is the most common cause and it is completely silent, because Android never asks your app. Check it:

If it is false, ask for the role. See Android call screening.

The device runs Android 9 or older. Call screening needs Android 10.

Another app holds the role. Android allows one screening app at a time. The user has to switch in Settings > Apps > Default apps > Caller ID and spam app.

Android: calls get blocked but no name appears

The overlay permission is missing. Check CallerAPI.canShowIncomingCallerIdOverlay(context), and send the user to Settings if it returns false.

Android: the first spam call always rings

This is by design. The SDK answers from its cache only. Android gives a screening app a very short window, and a network call does not fit in it safely.

An unknown number rings, and the SDK fetches the answer in the background for next time. Call prewarmAsync(number) when you know a number in advance.

iOS: my app is not listed in Settings > Phone > Call Blocking & Identification

Work through these in order. The first two account for most cases.

The extension bundle identifier is not nested under your app. It must be com.yourco.app.LiveLookup when your app is com.yourco.app.

The extension is not embedded. Open your built .app in Finder, choose Show Package Contents, and look for LiveLookup.appex in the Extensions folder. If it is missing, the target is not embedded in your app.

The device runs iOS 17 or older. Live Caller ID needs iOS 18.

The extension Info.plist is incomplete. It needs CFBundleExecutable, CFBundlePackageType set to XPC!, and EXExtensionPointIdentifier set to com.apple.live-lookup.

iOS: the install fails with "missing or invalid CFBundleExecutable"

Your extension Info.plist is missing CFBundleExecutable. Set it to $(EXECUTABLE_NAME).

iOS: signing fails with "amfid ... -413"

Your extension entitlements file contains the Live Caller ID Lookup entitlement, and your build is not an App Store build.

Make the entitlements file an empty <dict/> for local development. Add the capability only for TestFlight and App Store builds, and only after your relay enrollment is complete.

iOS: it works from Xcode and not from TestFlight

Expected until relay enrollment is finished.

A build from Xcode reaches our servers directly. TestFlight and App Store builds go through Apple's relay, and Apple only routes to a service registered in advance.

See iOS prerequisites.

iOS: I changed the extension and nothing changed

iOS caches extensions harder than apps. Delete the app from the device and install it again.

New installs fail while existing users are fine

You reached your device cap. Sandbox stops at 200 devices in a calendar month. Devices already counted keep working, so only new installs fail.

Check your device count in the dashboard. See Limits and billing.

Everything returns 429

You are rate limited. Read the Retry-After header.

During development this usually means the app restarts in a loop. Authentication is limited to 5 per minute per device, and a normal app authenticates about twice an hour.

Still stuck

Send us these four things. Without them we can only guess.

Your app name from the dashboard, not your credentials.

Your platform and SDK version.

The exact error text or the error code.

Whether a lookup of +18883578668 returns a name.

Every lookup returns nothing#

The app crashes with "CallerAPI not initialised"#

"CallerAPI native module is not available", React Native#

"CallerAPI.lookupLabel is not a function", React Native#

It works on Android and not on iOS, Flutter or React Native#

The Android build fails#

The iOS build fails#

The dashboard shows zero devices while lookups work#

Android: nothing happens on incoming calls#

Android: calls get blocked but no name appears#

Android: the first spam call always rings#

iOS: my app is not listed in Settings > Phone > Call Blocking & Identification#

iOS: the install fails with "missing or invalid CFBundleExecutable"#

iOS: signing fails with "amfid ... -413"#

iOS: it works from Xcode and not from TestFlight#

iOS: I changed the extension and nothing changed#

New installs fail while existing users are fine#

Everything returns 429#

Still stuck#