apache/cordova-android · error · RuntimeException

Expected Android Build Tools version >= ${cordovaConfig.MIN_

Error message

Expected Android Build Tools version >= ${cordovaConfig.MIN_BUILD_TOOLS_VERSION}, but got Android Build Tools version ${cordovaConfig.BUILD_TOOLS_VERSION}. Please use version ${cordovaConfig.MIN_BUILD_TOOLS_VERSION} or later.

What it means

After doApplyCordovaConfigCustomization applies overrides (the cdvBuildToolsVersion gradle property, or a hand-edited cdv-gradle-config.json BUILD_TOOLS_VERSION), cordova.gradle verifies with the versioncompare library that the resulting BUILD_TOOLS_VERSION is not below MIN_BUILD_TOOLS_VERSION. Unlike the auto-discovery errors, this one fires only when a version was explicitly supplied — so the offending value came from your -P flag, project gradle.properties, or config json.

Source

Thrown at framework/cordova.gradle:186

        cordovaConfig.BUILD_TOOLS_VERSION = cdvBuildToolsVersion
    }
    if (project.hasProperty('cdvAndroidXAppCompatVersion')) {
        cordovaConfig.ANDROIDX_APP_COMPAT_VERSION = cdvAndroidXAppCompatVersion
    }
    if (project.hasProperty('cdvAndroidXWebKitVersion')) {
        cordovaConfig.ANDROIDX_WEBKIT_VERSION = cdvAndroidXWebKitVersion
    }

    if (!cordovaConfig.BUILD_TOOLS_VERSION) {
        cordovaConfig.BUILD_TOOLS_VERSION = doFindLatestInstalledBuildTools(
            cordovaConfig.MIN_BUILD_TOOLS_VERSION
        )
    }

    // Ensure the configured build tools version is at least our declared minimum
    def buildToolsVersion = new Version(cordovaConfig.BUILD_TOOLS_VERSION)
    if (buildToolsVersion.isLowerThan(cordovaConfig.MIN_BUILD_TOOLS_VERSION)) {
        throw new RuntimeException("""
            Expected Android Build Tools version >= ${cordovaConfig.MIN_BUILD_TOOLS_VERSION},
            but got Android Build Tools version ${cordovaConfig.BUILD_TOOLS_VERSION}. Please use version ${cordovaConfig.MIN_BUILD_TOOLS_VERSION} or later.
        """.replaceAll(/\s+/, ' ').trim())
    }
}

def doVerifyCordovaConfigForBuild() {
    if (cordovaConfig.COMPILE_SDK_VERSION < cordovaConfig.SDK_VERSION) {
        println "The \"compileSdkVersion\" (${cordovaConfig.COMPILE_SDK_VERSION}) should be greater than or equal to the the \"targetSdkVersion\" (${cordovaConfig.SDK_VERSION})."
    }
}

// Properties exported here are visible to all plugins.
ext {
    def defaultsFilePath = './cdv-gradle-config-defaults.json'
    def projectConfigFilePath = "$rootDir/cdv-gradle-config.json"
    def targetConfigFilePath = null

View on GitHub (pinned to 7c1e190064)

Solutions

Drop the override — remove -PcdvBuildToolsVersion / the cdvBuildToolsVersion line so auto-discovery selects the newest installed version in the required series (>= minimum).
Or raise the pin to at least the minimum named in the message and install that exact package: sdkmanager 'build-tools;<version>'.
If you must stay on older build-tools than the platform minimum, downgrade cordova-android to a release whose MIN_BUILD_TOOLS_VERSION you satisfy.

Example fix

# before
$ ./gradlew assembleRelease -PcdvBuildToolsVersion=30.0.3
... Expected Android Build Tools version >= 35.0.0 ...

# after — let discovery pick an installed >= minimum version
$ ./gradlew assembleRelease
# or pin a valid one you installed:
$ sdkmanager 'build-tools;35.0.0' && ./gradlew assembleRelease -PcdvBuildToolsVersion=35.0.0

Defensive patterns

Strategy: validation

Validate before calling

# If your build pins build-tools, check the pin against the platform minimum first
if [ -n "$PIN" ]; then
  MIN=$(grep -oP '(?<=MIN_BUILD_TOOLS_VERSION": ")[^"]+' platforms/android/CordovaLib/cdv-gradle-config-defaults.json)
  [ "$(printf '%s\n' "$MIN" "$PIN" | sort -V | head -1)" = "$MIN" ] \
    || { echo "cdvBuildToolsVersion=$PIN is below platform minimum $MIN"; exit 1; }
fi

Prevention

Do not pin cdvBuildToolsVersion unless a reproducible CI toolchain requires it.
When you must pin, derive the pin from the platform's declared MIN_BUILD_TOOLS_VERSION in the same script instead of hardcoding an old value.
Re-check (or drop) all -Pcdv* pins after each cordova-android upgrade.

When it happens

Trigger: Building with ./gradlew -PcdvBuildToolsVersion=30.0.3 (a legacy value from old docs) while the platform requires a much higher minimum; cdvBuildToolsVersion pinned in the project's gradle.properties; cdv-gradle-config.json's BUILD_TOOLS_VERSION left at an old value after a cordova-android upgrade raised the minimum.

Common situations: CI build commands copy-pasted from an older project; teams that pin all tool versions by convention and carry the pin across platform upgrades; manual edits of cdv-gradle-config.json drifting from the platform's declared minimum.

Related errors

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