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.

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: I turned the SDK card off, and my UI never appears

setIncomingCallerIdOverlayEnabled(false) only hides the SDK name card. The SDK screening service still receives every call. Your code never sees the number.

To draw your own card, remove com.callerapi.sdk.CallerScreeningService with tools:node="remove", then write your own service. Answer Telecom with cachedSpamVerdict. Call lookupLabel after respondToCall. See Drawing your own name card.

Android: I wrote my own service, and the SDK card still appears

Gradle still merges the SDK screening service. Telecom can bind that one instead of yours.

Remove it in your manifest:

<service
    android:name="com.callerapi.sdk.CallerScreeningService"
    tools:node="remove" />

The <manifest> tag needs xmlns:tools="http://schemas.android.com/tools".

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 extension is listed and switched on, and nothing ever happens

Every call fails with NSCocoaErrorDomain code 4099, and this appears in Console:

activating connection: name=com.apple.CallKit.CallDirectory
failed to do a bootstrap look-up: xpc_error=[3: No such process]

Your app has not loaded CallKit. Live Caller ID reaches the system through an XPC service that lives inside CallKit.framework, and that service can only be found by a process with CallKit loaded. Without it every call fails before it starts: the status reads disabled however the toggle is set, refresh and reset throw, and nothing reaches our servers, so the dashboard looks quiet and healthy.

SDK 1.6.2 and later link CallKit for you, through the Swift package and the podspec. If you are on an earlier version, upgrade. If you built the SDK from copied sources rather than from the package, add CallKit.framework to that target yourself.

iOS: a number still shows no name after we added it

The device cached the earlier empty answer, and it keeps it for 24 hours. Publishing new data does not clear it, and neither does refreshPIRParameters, which refreshes the description of the dataset rather than any cached answer.

Clear it:

Then place the call again. Do this after any change to your data, otherwise you are testing yesterday's answer and the natural conclusion is that your change did not work.

iOS: the Settings toggle will not turn off, or reports an error

Settings shows "an error occurred while disabling the extension", and the toggle does not move.

The system lost track of your extension, usually after repeated installs while something was holding it open. Reboot the phone, which clears it. If it persists, delete the app, reboot, and install again.

An app on SDK 1.6.2 or later should not cause this. Earlier versions could, by launching the extension repeatedly to test whether it was enabled.

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.

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.

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: I turned the SDK card off, and my UI never appears#

Android: I wrote my own service, and the SDK card still appears#

Android: the first spam call always rings#

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

iOS: the extension is listed and switched on, and nothing ever happens#

iOS: a number still shows no name after we added it#

iOS: the Settings toggle will not turn off, or reports an error#

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#