"Unable to read configuration of AVD" when ANDROID_USER_HOME or ANDROID_SDK_HOME is set

[blindcat97]

Describe the bug

Briefcase is unable to run an Android emulator. When I select the emulator from the list, it produces the error Unable to read configuration of AVD @beePhone. Looking at the logs, this seems to stem from a missing config file, C:\\Users\\blind\\.android\\avd\\beePhone.avd\\config.ini which is not present on my drive. I searched my user folder for any sign of beePhone.avd and found nothing. I went into AppData and cleared the SDK folder from Briefcase's cache, and reinstalled the SDK and created a new emulator, but it still has this error.

Steps to reproduce

1. Prepare a project and build it for Android
2. Use briefcase run android and select a new emulated phone.
3. Phone fails to boot due to missing config

Expected behavior

I expect the emulator to boot.

Screenshots

No response

Environment

• Operating System: Windows 11
• Python version: 3.13
• Software versions:
  • Briefcase: 0.3.26
  • Toga: 0.5.3

Logs

briefcase.2025_12_10-21_07_39.run.log

Additional context

Note: This is NOT related to my last bug report that was due to a comma in the file path. This project is running in a separate test folder outside of any paths with unusual characters.

[rmartin16]

@blindcat97, I notice that ANDROID_SDK_HOME environment variable is set to C:\Android. Could you please check if there's a beePhone.avd in C:\Android\.android\avd?

[blindcat97]

Okay, there are avd configs for the emulators I tried to make. How do I associate them with the briefcase emulator? Just move them to C:\Users\blind\.android\avd\ ?

[rmartin16]

The best long term option would probably be to unset the ANDROID_SDK_HOME env var when running Briefcase or actually get Briefcase to use the Android SDK specified at ANDROID_SDK_HOME. Unfortunately, the env vars for Android and its ecosystem have organically grown and changed over time making it nearly impossible to sort them out in any arbitrary environment.

If you do want to try to get Briefcase to use the Android SDK in C:\Android, can you try setting ANDROID_HOME to C:\Android as well? From there, you'll need to make sure that Commandline Tools v19.0 is installed; this is most easily done through Android Studio if you have it set up to use this SDK as well.

[mhsmith]

can you try setting ANDROID_HOME to C:\Android as well?

No, don't do that. We're confusing two different things, whose environment variables are documented here:

• The Android SDK: recommended variable ANDROID_HOME, deprecated variable ANDROID_SDK_ROOT. Briefcase respects these variables, but if they're not set, it will install and use its own copy, which appears to be working fine in the log.
• The Android user data directory: recommended variable ANDROID_USER_HOME, deprecated variable ANDROID_SDK_HOME.

These two should definitely not be set to the same location!

The bug is that Briefcase does not respect ANDROID_USER_HOME or ANDROID_SDK_HOME, and always uses the default location of $HOME/.android. But the Android tools do respect these variables, so they'll create the AVD in a location where Briefcase can't find it.

Until this is fixed, you'll need to unset ANDROID_SDK_HOME so that everything uses the default location. I recommend that you don't try moving anything from C:\Android to this location, as it may not be relocatable. Just start the new location from scratch.

[rmartin16]

Thank you for that clarification; linking these related issues:

• Cannot support non-standard location for .android directory #1665
• Respect and pass through ANDROID_USER_HOME and ANDROID_AVD_HOME #1673
  • Which was followed by Revert "Respect and pass through ANDROID_USER_HOME and ANDROID_AVD_HOME" #1689