---
title: "Troubleshooting"
slug: "troubleshooting"
updated: 2026-09-28T12:41:47Z
published: 2026-09-28T12:41:47Z
canonical: "docs.mapp.com/troubleshooting"
---

> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mapp.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Troubleshooting

Here are some common issues you might encounter when integrating the Mapp Intelligence React Native SDK, along with suggested solutions:

## Issue 1: CocoaPods Installation Failure on iOS

**Problem:** Running `pod install` fails with an error, preventing the installation of necessary iOS dependencies.

**Solution:**

1. Ensure that CocoaPods is installed correctly by running `sudo gem install cocoapods`. If your project manages CocoaPods with Bundler, use `bundle exec pod install`.
2. Try clearing the CocoaPods cache by running `pod cache clean --all`.
3. Delete the `Podfile.lock` and `Pods/` directory from your iOS project and run `pod install` again.
4. Check that your iOS deployment target is at least 15.1 and that you use Xcode 16.1 or later.

---

## Issue 2: Android Build Fails with SDK or Kotlin Errors

**Problem:** The Android build fails with SDK compatibility errors, or with Kotlin metadata errors such as an incompatible Kotlin version.

**Solution:**

1. Check the root `android/build.gradle`: `minSdkVersion` must be at least 24, `compileSdkVersion` and `targetSdkVersion` at least 36.
2. Make sure the app uses a Kotlin 2.3 compiler. React Native's default Kotlin version is too old for the Mapp Android SDK.
3. Ensure that your JDK version is 21.
4. If you use a custom Gradle setup, make sure it provides the `com.android.library`, `org.jetbrains.kotlin.android`, and `com.facebook.react` plugins.
5. If you recently updated the SDK, clean your project by running `./gradlew clean` and rebuild.

---

## Issue 3: Initialization Fails with Network Errors

**Problem:** The SDK fails to initialize due to network issues, such as an inability to reach the tracking domain.

**Solution:**

1. Verify that the `TRACK_DOMAIN` URL is correct and accessible from your development environment.
2. Check your network connection and any firewall settings that might block outgoing requests.
3. Ensure that the app has the necessary permissions to access the internet on both Android and iOS platforms.

---

## Issue 4: Data Not Appearing in Mapp

**Problem:** Tracking data does not appear in Mapp Intelligence.

**Solution:**

1. Ensure that the `TRACK_IDS` and `TRACK_DOMAIN` are correctly configured during initialization.
2. Check if tracking requests are being sent by inspecting network logs or using a debugging proxy.
3. Verify that the `initWithConfiguration` method has been called successfully and that `isInitialized()` returns `true`.
4. Be aware that data updates in Mapp Intelligence occur on an hourly basis. This means that there may be a delay of up to one hour before newly tracked data appears in the dashboard. If data is not visible immediately, please allow some time before checking again.

---

## Issue 5: Changes Not Applied After Upgrading

**Problem:** After upgrading the SDK, the app still behaves like the old version, or the native module cannot be found.

**Solution:** A Metro reload does not update native code. Reinstall the iOS pods, then rebuild and reinstall both native apps. In Expo apps, run `npx expo prebuild --clean` before rebuilding the development build.

---

## Issue 6: SDK Does Not Work in Expo Go

**Problem:** The app runs in Expo Go, but the SDK does not load or tracking calls fail.

**Solution:** Expo Go is not supported, because the SDK contains native code. Create a development build with `expo-dev-client` and open that app instead. See [Expo Integration Guide](/docs/en/expo-integration-guide-react-native-intelligence).

---

## Issue 7: Expo Prebuild Fails with a Groovy Error

**Problem:** `npx expo prebuild` stops with the message that the Mapp Expo integration requires a Groovy root `build.gradle`.

**Solution:** The config plugin only supports a Groovy root `build.gradle`, which is the Expo default. If your project uses a Kotlin DSL build script, configure the Kotlin Gradle plugin version in that script yourself.