Guides
Start typing to search…

Troubleshooting

Resolve common React Native SDK integration issues and build errors

Troubleshooting

This guide covers the most common issues developers encounter when integrating StreamLayer into React Native applications.

Native Module Linking Failures

Symptoms:

  • "Cannot find native module StreamLayer" runtime error
  • NativeModules.StreamLayer is undefined
  • Auto-linking appears to have run but module still missing

Solution:

  1. Clear all caches and rebuild: 
    cd ios && rm -rf Pods Podfile.lock
cd .. && rm -rf node_modules && npm install
  2. Verify auto-linking: npx react-native config should list StreamLayer
  3. If auto-linking fails, manually link:
    • iOS: Add StreamLayer to Podfile with pod 'StreamLayer'
    • Android: Check android/build.gradle includes StreamLayer dependency
  4. Rebuild native code: npm run android or npm run ios
  5. Clear app cache on device: Settings → Apps → YourApp → Storage → Clear Cache

iOS Pod Install Failures

Symptoms:

  • pod install fails with incompatibility errors
  • Pod cache corrupted after network interruption
  • Xcode build fails with "Pods-YourApp" not found

Solution:

  1. Remove and reinstall pods: 
    cd ios && rm -rf Pods Podfile.lock && pod install
  2. Update pod repo: pod repo update
  3. Check Xcode version—update if outdated
  4. Verify iOS deployment target matches in Podfile: platform :ios, '12.0'
  5. For M1 Macs, add architecture support: post_install hook in Podfile

Android Build Failures

Symptoms:

  • Gradle sync fails in Android Studio
  • "Unsupported class-file format" errors
  • Minimum SDK version conflicts

Solution:

  1. Verify Gradle and AGP versions: 
    // gradle/wrapper/gradle-wrapper.properties
distributionUrl=https://services.gradle.org/gradle-8.0-bin.zip
  2. Check android/build.gradle compileSdkVersion >= 33
  3. Ensure JDK 11+ is installed: java -version
  4. Clear Gradle cache: rm -rf ~/.gradle/caches/
  5. Rebuild: cd android && ./gradlew clean build

Metro Bundler Issues

Symptoms:

  • Metro cache prevents bundler from seeing new native modules
  • "Cannot find module streamlayer" during bundling
  • Hot reload fails after dependency changes

Solution:

  1. Clear Metro cache: npx react-native start --reset-cache
  2. Kill old Metro processes: lsof -i :8081 | grep node | awk '{print $2}' | xargs kill
  3. Delete watchman cache: watchman watch-del-all
  4. For Expo projects, clear bundler cache and rebuild
  5. Restart Metro bundler after any native module changes

Expo-Specific Issues

Symptoms:

  • StreamLayer not available in Expo managed workflow
  • "Expo Go doesn't support this module" message
  • Bare workflow works but managed doesn't

Solution:

  1. Confirm project is running bare workflow—StreamLayer requires it
  2. If using managed workflow, eject to bare: expo prebuild --clean
  3. After ejecting, follow iOS and Android troubleshooting guides
  4. Verify eas.json includes StreamLayer in plugins if using EAS build
  5. Test locally with npm run ios and npm run android before EAS builds

Still Need Help?

If you've tried these solutions and still encounter issues, contact our support team at [email protected] with:

  • Full error logs and stack traces
  • React Native version and platform (Expo managed/bare, RN CLI)
  • Node and npm versions (node -v && npm -v)

Related

Updated 21 days ago