Troubleshooting

Solutions to common issues you may encounter when developing Space7 on Android.

This page covers problems frequently encountered during local development. Each section describes the symptom and provides step-by-step commands to resolve it.

Metro is already running or stuck on the wrong port

Symptom: Running npm run android or npm run dev prints an error like Metro is already running or the bundler serves from an unexpected port, causing the app to fail to connect.

Solution:

1. Find and kill the existing Metro process

   On Linux/macOS, identify the process occupying port 8081:

   lsof -ti :8081 | xargs kill -9
   

   Alternatively, use your system’s process manager to end any node process running react-native start.

2. Restart Metro

   npm run dev
   
3. Relaunch the app in a second terminal

   npm run android
   

If Metro keeps restarting unexpectedly, try resetting its cache: npm run dev -- --reset-cache

Android build fails after adding or changing a native dependency

Symptom: npm run android fails with a Gradle error after you added, removed, or upgraded a library that has native Android code.

Solution:

1. Run the clean build script

   This removes stale C++ build artefacts, clears Gradle-generated autolinking files, runs ./gradlew clean, and then rebuilds:

   npm run android:clean
   
2. Check if the dependency requires manual Android setup

   Some libraries require additional steps in android/app/build.gradle or AndroidManifest.xml. Consult the library’s documentation if android:clean alone does not resolve the error.

android:clean deletes build artefacts and triggers a full Gradle rebuild. Expect it to take several minutes on the first run after cleaning.

Device not detected by adb

Symptom: adb devices returns an empty list, or the device shows as unauthorized.

Solution:

1. Verify USB debugging is enabled

   On your Android device:

   • Open Settings → About phone and tap Build number seven times to enable Developer Options.
   • Open Settings → Developer options and turn on USB debugging.
   • When prompted on the device screen, tap Allow to authorise your computer.
2. Check the USB connection mode

   Make sure the USB cable is in data transfer mode (MTP or file transfer), not charge-only mode.

3. Restart the adb server

   adb kill-server
   adb start-server
   adb devices
   
4. Verify adb is in your PATH

   If adb is not found, add Android platform-tools to your shell profile:

   export ANDROID_HOME=$HOME/Library/Android/sdk   # macOS
   export PATH=$PATH:$ANDROID_HOME/platform-tools
   

   Then reload your shell: source ~/.zshrc (or ~/.bashrc).

Gradle sync fails or SDK path is invalid

Symptom: Gradle fails with errors about a missing SDK, unresolved dependencies, or incompatible build tools versions.

Solution:

1. Open the android/ directory in Android Studio

   open android
   

   Or launch Android Studio and choose Open → <project-root>/android.

2. Check the SDK path

   In Android Studio go to File → Project Structure → SDK Location and confirm the Android SDK path is valid and points to an installed SDK.

3. Install required SDK packages

   Open SDK Manager (the puzzle-piece icon in the toolbar) and install the API level and build tools versions referenced in android/app/build.gradle.

4. Trigger a Gradle sync

   Click File → Sync Project with Gradle Files. Address any errors reported in the Build output panel.

App behaves unexpectedly after a dependency change (cache issues)

Symptom: After running npm install or changing a dependency, the app exhibits stale behaviour — showing old screens, crashing on import, or failing to resolve a module — even though the source code looks correct.

Solution:

1. Reset the Metro cache

   npm run dev -- --reset-cache
   

   Leave Metro running.

2. Clean and rebuild the Android app

   In a second terminal:

   npm run android:clean
   

Running both steps together ensures neither the JavaScript bundle cache nor the native build artefacts contain stale data.

TypeScript errors or unexpected lint failures

Symptom: Your editor shows TypeScript errors or Biome reports lint violations after pulling new code or refactoring.

Solution:

1. Run Biome auto-fix

   Most formatting and safe lint issues are fixed automatically:

   npm run biome:run
   
2. Review remaining errors manually

   Errors that Biome cannot auto-fix (e.g. type mismatches) are printed to the console. Fix them in your editor using the reported file paths and line numbers.

3. Confirm the TypeScript compiler is satisfied

   npx tsc --noEmit
   

The Biome configuration in biome.json excludes android/, ios/, node_modules/, and vendor/, so you only see errors for your own source files.

Missing environment variables — network requests all fail

Symptom: All API calls fail silently, the Socket.IO connection never establishes, or you see errors referencing an empty URL. This happens when SERVER_ENDPOINT is not set.

Solution:

1. Create a .env file in the project root

   touch .env
   
2. Add the SERVER_ENDPOINT variable

   SERVER_ENDPOINT=http://your-backend-host:port
   

   Replace http://your-backend-host:port with your actual backend URL. When running on an Android emulator, 10.0.2.2 maps to your host machine’s localhost.

   SERVER_ENDPOINT=http://10.0.2.2:3000
   
3. Restart Metro and rebuild

   Environment variables are baked into the bundle at build time by react-native-dotenv. Metro must be restarted with a cache reset for the new value to take effect:

   npm run android:fresh
   

Do not commit your .env file to version control. Add it to .gitignore to prevent accidentally leaking your backend endpoint.