Troubleshooting

Common issues and solutions for NextNative development.

Setup & Environment

Node Version Issues

Solution: Upgrade Node.js to version 20 or higher from nodejs.org (opens in a new tab).

Android Studio on Mac M1-M4

Solution: Use the Android Studio Ladybug October 2024 release instead of the latest version for better stability on Apple Silicon Macs.

iOS Development

Running on Real Device

Solution: Follow the rename your app guide before attempting to run on a physical iOS device.

Firebase Authorization Setup

Solution: Complete the app renaming process before configuring Firebase Auth to avoid bundle ID conflicts.

Android Development

Firebase Configuration

Solution: Rename your app before setting up Firebase to ensure the package name matches your Firebase configuration.

Google Services Plugin

apply plugin: 'com.google.gms.google-services'

Solution: If you're not using Firebase, remove the google-services plugin from your build.gradle to avoid build errors.

Build.gradle Already Updated

Note: If you have the latest version of NextNative, the Firebase configuration in build.gradle is already properly set up.

Package Renaming Didn't Work

Solution: Manually rename the directory structure and update the package declaration in MainActivity.java if Android Studio's refactor tool fails.

Testing Google Login on M1/M2/Windows

Solution: Use a real Android device to test Google login if you're on Mac M1/M2 or Windows PC, as emulators may not work reliably for this feature.

Live Reload & Development

Firewall Blocking Live Reload

Solution: Temporarily disable your firewall or add an exception for your development server to allow the mobile app to connect to the live reload server.

Deployment

Running Production Build

Note: Always run npm run mobile before deploying to ensure your app has the latest production build.

Important: Run npm run mobile every time you make code changes before building for production or testing on devices.

API & Backend

Production URL Not Set

Solution: Update the NEXT_PUBLIC_PRODUCTION_URL environment variable in your .env.local file to point to your deployed API endpoint before releasing your app.

Missing Authorization Token

Solution: Ensure you're properly obtaining and storing the authentication token from your auth provider before making authenticated API requests.

In-App Purchases

Products Not Configured in Stores

Solutions:

1. Configure your products in App Store Connect (iOS) or Google Play Console (Android) before setting up RevenueCat
2. For iOS: Sign the Paid Applications Agreement and complete bank/tax information in App Store Connect before testing purchases
3. Import products into RevenueCat after configuring them in the respective stores

Cache & Build Issues

Android Studio Cache Issues

After changing your app's package name, namespace, and Java folder structure, Android Studio might still hold on to outdated paths or cached builds. This can lead to strange build errors or the old app ID being used silently.

Solution:

1. Clean the Project: Menu → Build → Clean Project (removes stale build files)
2. Invalidate Caches and Restart: Menu → File → Invalidate Caches → Click 🟦 Invalidate and Restart

This will wipe Android Studio's internal caches, restart, and rebuild everything from scratch using the new package name and paths.

CORS Issues

Preflight Request Failing

When sending requests from a mobile app, especially with custom headers, the browser or WebView may first send an OPTIONS preflight request. If your API route doesn't respond to it, the request will fail.

Solution: Add an OPTIONS handler to your API routes:

// app/api/chat/route.ts
export async function OPTIONS() {
  return new Response(null, {
    status: 204,
    headers: {
      "Access-Control-Allow-Origin": "*",
      "Access-Control-Allow-Methods": "GET,POST,OPTIONS",
      "Access-Control-Allow-Headers": "Content-Type, Authorization",
    },
  });
}

This ensures your endpoint handles preflight checks properly, allowing mobile apps to make authenticated requests.

Need More Help?

If you're experiencing an issue not covered here:

1. Check the Capacitor documentation (opens in a new tab) for native plugin issues
2. Review the Firebase documentation (opens in a new tab) for Firebase-related problems
3. Consult the Next.js documentation (opens in a new tab) for framework-specific questions