Troubleshooting
Most problems come from one of four places: the SDK path, the JDK version, the first download, or the device connection. Find your symptom below.
Quick fixes
| Symptom | Fix |
|---|---|
Android SDK : Not auto-detected | export ANDROID_HOME=~/Library/Android/sdk (or your SDK path) |
No installed Android Virtual Devices | Create one in Android Studio → Device Manager, or plug in a phone with USB debugging enabled |
Could not download gradle-wrapper.jar | Connect to the internet for the first build, or run gradle wrapper in the output folder |
| Build fails after a JDK change | Point JAVA_HOME at JDK 17 or newer |
| Phone not found | Check the cable, accept the "Allow USB debugging?" prompt, then run adb devices |
Android SDK not found
The script checks ANDROID_HOME, then ANDROID_SDK_ROOT, then the default Android Studio location. Typical paths:
| System | Default SDK path |
|---|---|
| macOS | ~/Library/Android/sdk |
| Linux | ~/Android/Sdk |
| Windows | %LOCALAPPDATA%\Android\Sdk |
To find yours, open Android Studio → Settings → Languages & Frameworks → Android SDK and copy the "Android SDK Location". Add the export line to your shell profile so it sticks.
JDK version errors
Errors such as "Unsupported class file major version" or "requires Java 17" mean Gradle is running on an old JDK. Check with java -version, then set JAVA_HOME to a JDK 17 or newer. Android Studio's bundled JDK works.
The first build is slow or fails to download
The first build downloads the Gradle distribution, the Android Gradle Plugin and the AndroidX libraries. On a slow connection that can take several minutes. If the wrapper jar can't be downloaded, the script tells you; connect and run it again, or run gradle wrapper inside android_build/ if you have Gradle installed. After the first build, everything is cached and builds work offline.
No emulator available
Run python3 android_scaffold.py src --list-emulators. If the list is empty, create a virtual device in Android Studio's Device Manager. If the emulator starts but never finishes booting, cold-boot it from Device Manager, and make sure hardware acceleration is available on your machine.
Phone not detected or unauthorized
- Use a data-capable USB cable. Some charging cables carry no data.
- Unlock the phone and accept the "Allow USB debugging?" prompt.
- Run
adb devices. A phone listed asunauthorizedis waiting for that prompt; one listed asdeviceis ready. - If it still doesn't appear, toggle USB debugging off and on, or run
adb kill-serverand try again.
Install fails with a signature conflict
If a version of the app with the same application ID was installed from somewhere else, adb install -r refuses to replace it. Uninstall the old copy from the phone, or adb uninstall com.your.package, and run again.
Frequently asked questions
Where do I set ANDROID_HOME permanently?
On macOS and Linux add export ANDROID_HOME="$HOME/Library/Android/sdk" (or your path) to ~/.zshrc or ~/.bashrc. On Windows set it under System Properties, Environment Variables.
Why does the build work in Android Studio but not from the terminal?
Android Studio uses its own bundled JDK. The terminal uses whatever java is on your PATH. Point JAVA_HOME at the Android Studio JDK or install JDK 17 or newer.
How do I start over with a clean project?
Delete the android_build/ folder and run the script again. Your source folder is never modified, so nothing is lost.