{"record":{"id":"8c95b47e24f8d778","repo":"apple/pkl","slug":"plugin-org-pkl-requires-gradle-s-or-higher","errorCode":null,"errorMessage":"Plugin `org.pkl` requires Gradle %s or higher.","messagePattern":"Plugin `org\\.pkl` requires Gradle (.+?) or higher\\.","errorType":"exception","errorClass":"GradleException","httpStatus":null,"severity":"error","filePath":"pkl-gradle/src/main/java/org/pkl/gradle/PklPlugin.java","lineNumber":77,"sourceCode":"import org.pkl.gradle.task.JavaCodeGenTask;\nimport org.pkl.gradle.task.KotlinCodeGenTask;\nimport org.pkl.gradle.task.ModulesTask;\nimport org.pkl.gradle.task.PkldocTask;\nimport org.pkl.gradle.task.ProjectPackageTask;\nimport org.pkl.gradle.task.ProjectResolveTask;\nimport org.pkl.gradle.task.TestTask;\nimport org.pkl.gradle.utils.PluginUtils;\n\n@SuppressWarnings(\"unused\")\npublic class PklPlugin implements Plugin<Project> {\n\n  private static final String MIN_GRADLE_VERSION = \"8.2\";\n\n  @Override\n  public void apply(Project project) {\n\n    if (GradleVersion.current().compareTo(GradleVersion.version(MIN_GRADLE_VERSION)) < 0) {\n      throw new GradleException(\n          String.format(\"Plugin `org.pkl` requires Gradle %s or higher.\", MIN_GRADLE_VERSION));\n    }\n\n    var extension = project.getExtensions().create(\"pkl\", PklExtension.class);\n    configureExtension(project, extension);\n  }\n\n  private void configureExtension(Project project, PklExtension extension) {\n    configureEvalTasks(project, extension.getEvaluators());\n    configureJavaCodeGenTasks(project, extension.getJavaCodeGenerators());\n    configureKotlinCodeGenTasks(project, extension.getKotlinCodeGenerators());\n    configurePkldocTasks(project, extension.getPkldocGenerators());\n    configureTestTasks(project, extension.getTests());\n    configureProjectPackageTasks(project, extension.getProject().getPackagers());\n    configureProjectResolveTasks(project, extension.getProject().getResolvers());\n    configureAnalyzeImportsTasks(project, extension.getAnalyzers().getImports());\n  }\n","sourceCodeStart":59,"sourceCodeEnd":95,"githubUrl":"https://github.com/apple/pkl/blob/f3efcbfc9b60d30053b0536d664948d7aa1b8673/pkl-gradle/src/main/java/org/pkl/gradle/PklPlugin.java#L59-L95","documentation":"The org.pkl Gradle plugin requires a minimum Gradle version (8.2 as of MIN_GRADLE_VERSION). During apply(), it compares GradleVersion.current() against that minimum and throws GradleException when the running Gradle is older. This prevents the plugin from using APIs that do not exist in older Gradle versions.","triggerScenarios":"Applying the pkl plugin in a build whose Gradle runtime is below the minimum, e.g. running with an old wrapper distribution or invoking an outdated system Gradle instead of ./gradlew.","commonSituations":"gradle/wrapper/gradle-wrapper.properties still pinned to an old distribution; CI images with a preinstalled Gradle older than 8.2; developers typing `gradle` instead of `./gradlew`; upgrading the plugin without upgrading the wrapper.","solutions":["Update the Gradle wrapper: edit gradle/wrapper/gradle-wrapper.properties distributionUrl to a Gradle 8.2+ distribution (or run `./gradlew wrapper --gradle-version 8.2`).","Run builds via ./gradlew rather than a system-installed `gradle` that may be older.","Pin a compatible older version of the pkl plugin if the wrapper cannot be upgraded.","Update CI/Docker images so the Gradle on PATH is >= 8.2."],"exampleFix":"// before (gradle/wrapper/gradle-wrapper.properties)\ndistributionUrl=https\\://services.gradle.org/distributions/gradle-7.6-bin.zip\n// after\ndistributionUrl=https\\://services.gradle.org/distributions/gradle-8.2-bin.zip","handlingStrategy":"validation","validationCode":"if (GradleVersion.current() < GradleVersion.version(\"8.2\")) throw GradleException(\"Use Gradle >= 8.2 for org.pkl plugin\")","typeGuard":"static boolean gradleSupported() { return GradleVersion.current().compareTo(GradleVersion.version(\"8.2\")) >= 0; }","tryCatchPattern":"try { apply plugin } catch (GradleException e) { if (e.message?.contains('requires Gradle')) logger.error('Run ./gradlew wrapper --gradle-version 8.2'); throw e }","preventionTips":["Always run builds via ./gradlew, never a system gradle","Keep gradle-wrapper.properties in sync with plugin minimums","Bump wrapper version when upgrading the pkl plugin","Check plugin README for minimum Gradle before applying"],"tags":["gradle","version-check","build","incompatibility"],"backgroundTag":"invalid-config-value","analyzedSha":"f3efcbfc9b60d30053b0536d664948d7aa1b8673","analyzedAt":"2026-09-08T13:10:45.570Z","contentChangedAt":"2026-09-08T13:10:45.570Z","schemaVersion":2},"datasetVersion":"2026-09-17T15:17:12.973Z"}