Use this file to discover all available pages before exploring further.
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-serveradb start-serveradb devices
4
Verify adb is in your PATH
If adb is not found, add Android platform-tools to your shell profile:
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.
