he Ultimate Capacitor & Android Developer Survival Guide

The Ultimate Capacitor & Android Developer Survival Guide

Transitioning from web code to a live Android app is exciting, but it's full of hidden traps, permission errors, and version conflicts. Here is my complete, battle-tested cheat sheet and troubleshooting guide!

Part 1: The Essential Commands

💻 1. Windows System Setup

Set-ExecutionPolicy RemoteSigned -Scope CurrentUser

Allows local PowerShell scripts (like NPM and Gradle) to run without needing full Administrator privileges.

🌐 2. Web & Capacitor Sync

npm install

Downloads all required Node modules for your project.

npm run sync

Custom script to build HTML/JS assets and copy them to the Android folder.

npx cap open android

Opens the official Android Studio interface directly from your VS Code terminal.

🤖 3. Compiling Android (Gradle)

cd android

Navigates into the Android native folder.

.\gradlew assembleDebug

Compiles your web code into a fresh, installable app-debug.apk file.

.\gradlew clean

Deletes cached build files. Run this if Android Studio starts acting crazy!

cd ..

Navigates back out to your main project folder.

📱 4. Wireless Deployment (ADB)

adb devices

Lists all phones connected to your computer.

adb tcpip 5555

Opens the port for Wi-Fi debugging (Requires USB cable for first setup).

adb connect YOUR_PHONE_IP:5555

Connects your computer to your phone wirelessly.

adb install -r android\app\build\outputs\apk\debug\app-debug.apk

Pushes the newly built app to your phone and overwrites the old version.

adb shell am start -n com.your.app/com.your.app.MainActivity

Forces the phone to open your app automatically.

🐙 5. Git & GitHub Flow

git status

Shows unsaved files and timeline health.

git add .

Stages all changes.

git commit -m "Your update message"

Saves a permanent snapshot.

git pull origin main --rebase

Safely stacks your local work on top of cloud updates without messy merge nodes.

git rebase --continue

Run this to finish stacking after fixing a Git conflict.

git push origin main

Uploads code to GitHub.

Part 2: Common Bugs & How to Fix Them

💥 The "Disabled Scripts" PowerShell Error

npm : File C:\...\npm.ps1 cannot be loaded because running scripts is disabled on this system.

The Fix: Windows is being overly protective. Run Set-ExecutionPolicy RemoteSigned -Scope CurrentUser once to allow local developer scripts to run.

💥 Git Conflict Breaking JSON

npm error JSON.parse Invalid package.json: JSONParseError... while parsing near "...<<<<<<< HEAD"

The Fix: You have Git merge conflict markers literally injected into your package.json file. Open the file, delete the <<<<<<< HEAD, =======, and >>>>>>> lines, pick one version of the code, and save.

💥 GitHub Actions Build Failing (Windows vs Linux)

sh: 1: Syntax error: end of file unexpected
Error: Process completed with exit code 2.

The Fix: You used Windows commands (like xcopy or rd) in your package.json, but GitHub runs on Linux! Change your build script to use the cross-platform tool shx instead:
"build": "npx --yes shx rm -rf www && npx --yes shx mkdir -p www && npx --yes shx cp -r src/* www"

💥 Android Gradle Plugin (AGP) Version Mismatch

The project is using an incompatible version (AGP 8.13.0)... Latest supported version is AGP 8.11.0

The Fix: Your code wants a newer build tool than your Android Studio supports. Open android/variables.gradle or android/build.gradle and downgrade the classpath version from 8.13.0 to 8.11.0.

💥 GitHub Actions Node & Java Version Errors

The Capacitor CLI requires NodeJS >=22.0.0 invalid source release: 21 (Java compilation initialization error)

The Fix: Your cloud server is using outdated software. Open your .github/workflows/android_build.yml file. Change your setup-node step to use node-version: '22', and add a setup-java step using java-version: '21'.

💥 ADB Installation Blocked

Failure [INSTALL_FAILED_USER_RESTRICTED: Install canceled by user]

The Fix: Your phone blocked the install via ADB. Run the command again and immediately look at your phone screen to tap "Allow/Install". If no pop-up appears, go to Developer Options and turn on Install via USB.

💥 Git "Pull with Rebase" Failing

error: cannot pull with rebase: You have unstaged changes. Please commit or stash them.

The Fix: Git refuses to download updates if your "desk is messy." Run git add . and git commit -m "wip" to save your work, THEN run your git pull origin main --rebase command.

💥 Missing App UI Element in Java

Cannot resolve symbol 'top_app_bar'

The Fix: Your Java file is trying to connect to a UI element that doesn't exist in your XML layout. Open your activity_main.xml and ensure your element actually has android:id="@+id/top_app_bar" attached to it.

💥 The Keystore "48-Hour Lock" Confusion

Waiting for Google to send the new Keystore file after resetting it in the Play Console.

The Reality: Google never sends you a Keystore file. When you request a reset, you upload a .pem certificate. Google locks your account for exactly 48 hours for security, then automatically activates it. After 48 hours, simply sign your App Bundle (.aab) using the .jks file you generated on your own computer!