apache/cordova-android · error · CordovaError

Failed to find 'ANDROID_HOME' environment variable. Try sett

Error message

Failed to find 'ANDROID_HOME' environment variable. Try setting it manually.
Detected 'avdmanager' command at ${parentDir} but does not appear to be within an Android SDK installation.
Try reinstall Android SDK or update your PATH to include valid path to SDK

What it means

SDK-detection branch when ANDROID_HOME is unset but avdmanager is on PATH: the SDK root is accepted only if avdmanager's path contains a 'cmdline-tools' segment (layout <sdk>/cmdline-tools/<ver>/bin, resolved with ../../../..). Thrown when avdmanager comes from somewhere else, e.g. the deprecated tools/ package of an old SDK layout.

Source

Thrown at lib/check_reqs.js:225

            let parentDir, grandParentDir;
            if (adbInPath) {
                parentDir = path.dirname(adbInPath);
                grandParentDir = path.dirname(parentDir);
                if (path.basename(parentDir) === 'platform-tools') {
                    maybeSetAndroidHome(grandParentDir);
                } else {
                    throw new CordovaError('Failed to find \'ANDROID_HOME\' environment variable. Try setting it manually.\n' +
                        'Detected \'adb\' command at ' + parentDir + ' but no \'platform-tools\' directory found near.\n' +
                        'Try reinstall Android SDK or update your PATH to include valid path to SDK' + path.sep + 'platform-tools directory.');
                }
            }
            if (avdmanagerInPath) {
                let sdkPath = null;
                if (/cmdline-tools/.test(avdmanagerInPath)) {
                    sdkPath = path.resolve(avdmanagerInPath, '../../../..');
                    maybeSetAndroidHome(sdkPath);
                } else {
                    throw new CordovaError('Failed to find \'ANDROID_HOME\' environment variable. Try setting it manually.\n' +
                        'Detected \'avdmanager\' command at ' + parentDir + ' but does not appear to be within an Android SDK installation.\n' +
                        'Try reinstall Android SDK or update your PATH to include valid path to SDK');
                }
            }
        }
        if (!process.env.ANDROID_HOME) {
            throw new CordovaError('Failed to find \'ANDROID_HOME\' environment variable. Try setting it manually.\n' +
                'Failed to find \'android\' command in your \'PATH\'. Try update your \'PATH\' to include path to valid SDK directory.');
        }
        if (!fs.existsSync(process.env.ANDROID_HOME)) {
            throw new CordovaError('\'ANDROID_HOME\' environment variable is set to non-existent path: ' + process.env.ANDROID_HOME +
                '\nTry update it manually to point to valid SDK directory.');
        }
        // Next let's make sure relevant parts of the SDK tooling is in our PATH
        if (hasAndroidHome && !adbInPath) {
            process.env.PATH += path.delimiter + path.join(process.env.ANDROID_HOME, 'platform-tools');
        }
        if (hasAndroidHome && !avdmanagerInPath) {

View on GitHub (pinned to 7c1e190064)

Solutions

Install modern command-line tools: `sdkmanager "cmdline-tools;latest"` (or Android Studio > SDK Manager > SDK Tools).
Export ANDROID_HOME explicitly so inference is not needed.
Update PATH to $ANDROID_HOME/cmdline-tools/latest/bin and remove the legacy tools/bin entry.

Example fix

# before
export PATH="$HOME/sdk/tools/bin:$PATH"

# after
export ANDROID_HOME="$HOME/Android/Sdk"
export PATH="$ANDROID_HOME/cmdline-tools/latest/bin:$ANDROID_HOME/platform-tools:$PATH"

Defensive patterns

Strategy: validation

Validate before calling

const avdmanager = process.env.PATH.split(path.delimiter)
  .map(d => path.join(d, 'avdmanager'))
  .find(p => fs.existsSync(p));

if (avdmanager && !/cmdline-tools/.test(avdmanager) && !process.env.ANDROID_HOME) {
  throw new Error('avdmanager is from a legacy SDK layout - set ANDROID_HOME and install cmdline-tools;latest');
}

Try / catch

try {
  await check_reqs.check_android();
} catch (e) {
  if (/avdmanager/.test(e.message)) {
    // guide: sdkmanager "cmdline-tools;latest" + export ANDROID_HOME
  }
  throw e;
}

Prevention

Keep SDK tooling on the modern layout: <sdk>/cmdline-tools/latest/bin plus <sdk>/platform-tools on PATH.
Remove legacy tools/bin PATH entries when upgrading old SDK installs.
Prefer setting ANDROID_HOME explicitly over relying on PATH inference.

When it happens

Trigger: `cordova requirements android` / build with avdmanager under $ANDROID_HOME/tools/bin (pre-2019 SDK layout) or a copied/shimmed binary, while ANDROID_HOME/ANDROID_SDK_ROOT are unset.

Common situations: Legacy machines or CI images still carrying the old AndroidSDK 'tools' package; PATH entries added years ago pointing at tools/bin; SDK installed via old tarball.

Understand the failure class

Background: "environment variable is not set" and "Missing keys in environment" errors: what missing required env var messages mean and how to fix them — this error's family across 28 libraries.

Related errors

AI-assisted analysis of apache/cordova-android@7c1e190064 (2026-08-22). Data as JSON: /api/errors/5058528334fc750f. Report an issue: GitHub.