apache/cordova-android · error · GradleException

The defined Kotlin version (${cordovaConfig.KOTLIN_VERSION})

Error message

The defined Kotlin version (${cordovaConfig.KOTLIN_VERSION}) does not appear to be a valid version.

What it means

In the generated app template's buildscript block, when Kotlin is enabled (IS_GRADLE_PLUGIN_KOTLIN_ENABLED), KOTLIN_VERSION is validated with cdvHelpers.isVersionValid — implemented in cordova.gradle as !(new Version(v)).isEqual('0.0.0'), where 0.0.0 is the versioncompare library's sentinel for an unparseable string. A false result means the configured Kotlin version is not a parseable semantic version. The value comes from cdv-gradle-config.json (or CordovaLib's cdv-gradle-config-defaults.json) and is frequently written or adjusted by plugins.

Source

Thrown at templates/project/app/build.gradle:37

apply plugin: 'com.android.application'

if (cordovaConfig.IS_GRADLE_PLUGIN_KOTLIN_ENABLED) {
    apply plugin: 'kotlin-android'

    if(!cdvHelpers.isVersionGreaterThanEqual(cordovaConfig.KOTLIN_VERSION, '1.8.0')) {
        println "Kotlin version < 1.8.0 detected. Applying kotlin-android-extensions plugin."
        apply plugin: 'kotlin-android-extensions'
    }
}

buildscript {
    apply from: '../CordovaLib/cordova.gradle'

    // Checks if the kotlin version format is valid.
    if(cordovaConfig.IS_GRADLE_PLUGIN_KOTLIN_ENABLED) {
        if(!cdvHelpers.isVersionValid(cordovaConfig.KOTLIN_VERSION)) {
            throw new GradleException("The defined Kotlin version (${cordovaConfig.KOTLIN_VERSION}) does not appear to be a valid version.")
        }
    }

    apply from: 'repositories.gradle'
    repositories repos

    dependencies {
        classpath "com.android.tools.build:gradle:${cordovaConfig.AGP_VERSION}"

        if (cordovaConfig.IS_GRADLE_PLUGIN_KOTLIN_ENABLED) {
            classpath "org.jetbrains.kotlin:kotlin-gradle-plugin:${cordovaConfig.KOTLIN_VERSION}"
        }

        if(cordovaConfig.IS_GRADLE_PLUGIN_GOOGLE_SERVICES_ENABLED) {
            // Checks if the kotlin version format is valid.
            if(!cdvHelpers.isVersionValid(cordovaConfig.GRADLE_PLUGIN_GOOGLE_SERVICES_VERSION)) {
                throw new GradleException("The defined Google Services plugin version (${cordovaConfig.GRADLE_PLUGIN_GOOGLE_SERVICES_VERSION}) does not appear to be a valid version.")
            }

View on GitHub (pinned to 7c1e190064)

Solutions

Open platforms/android/cdv-gradle-config.json and set KOTLIN_VERSION to a full release semver, e.g. "1.9.24".
Identify which plugin rewrites that key and fix/update the plugin (often via its plugin variable) instead of fighting the generated file.
If Kotlin is not actually needed, set IS_GRADLE_PLUGIN_KOTLIN_ENABLED to false — the validation is skipped entirely.
Reset a sane baseline with cordova platform rm android && cordova platform add android, then re-apply plugin configuration in a controlled way.

Example fix

// before — platforms/android/cdv-gradle-config.json
"KOTLIN_VERSION": "${kotlin_version}",

// after
"KOTLIN_VERSION": "1.9.24",

Defensive patterns

Strategy: validation

Validate before calling

# Validate the Kotlin version string before invoking gradle
V=$(node -pe "JSON.parse(require('fs').readFileSync('platforms/android/cdv-gradle-config.json','utf8')).KOTLIN_VERSION")
case "$V" in
  [0-9]*.[0-9]*.[0-9]*) ;;
  *) echo "KOTLIN_VERSION '$V' is not a valid version (expected e.g. 1.9.24)"; exit 1 ;;
esac

Prevention

Treat cdv-gradle-config.json as generated output — change Kotlin settings through the plugin or build-extras that owns them, not by hand.
Add a before_prepare hook or CI pre-step that validates all *VERSION keys parse as semver.
After adding/removing Kotlin-dependent plugins, diff cdv-gradle-config.json to catch half-written values.

When it happens

Trigger: KOTLIN_VERSION in cdv-gradle-config.json is an empty string, a variable placeholder like ${kotlin_version}, 'latest', '1.9+', or any malformed semver; a plugin that customizes Kotlin settings wrote a bad value; the config json was hand-edited or left half-written by an interrupted plugin install.

Common situations: Adding Kotlin-heavy plugins (e.g. Firebase-flavored plugins) that rewrite gradle config; manually editing platforms/android/cdv-gradle-config.json; config drift after cordova platform rm/add cycles; plugin versions incompatible with the current cordova-android template.

Related errors

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