apple/pkl · error · GradleException

Plugin `org.pkl` requires Gradle

Error message

Plugin `org.pkl` requires Gradle %s or higher.

What it means

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.

Solutions

1. 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`).
2. Run builds via ./gradlew rather than a system-installed `gradle` that may be older.
3. Pin a compatible older version of the pkl plugin if the wrapper cannot be upgraded.
4. Update CI/Docker images so the Gradle on PATH is >= 8.2.

Example fix

// before (gradle/wrapper/gradle-wrapper.properties)
distributionUrl=https\://services.gradle.org/distributions/gradle-7.6-bin.zip
// after
distributionUrl=https\://services.gradle.org/distributions/gradle-8.2-bin.zip

if (GradleVersion.current() < GradleVersion.version("8.2")) throw GradleException("Use Gradle >= 8.2 for org.pkl plugin")

static boolean gradleSupported() { return GradleVersion.current().compareTo(GradleVersion.version("8.2")) >= 0; }

try { apply plugin } catch (GradleException e) { if (e.message?.contains('requires Gradle')) logger.error('Run ./gradlew wrapper --gradle-version 8.2'); throw e }

When it happens

Trigger: 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.

Common situations: 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.

Understand the failure class

Background: "Invalid value" and "allowed values are" config errors: what your library rejected and how to fix it — this error's family across 41 libraries.

Related errors

• Failed to parse transitive imports from
• Could not find a source set for code generator
• Failed to load class path resource `$resourceName`.
• Failed to parse Pkl module file path
• Failed to parse Pkl module file path

AI-assisted analysis of apple/pkl@f3efcbfc9b (2026-09-08). Data as JSON: /api/errors/8c95b47e24f8d778. Report an issue: GitHub.

Appendix: source

Thrown at pkl-gradle/src/main/java/org/pkl/gradle/PklPlugin.java:77

import org.pkl.gradle.task.JavaCodeGenTask;
import org.pkl.gradle.task.KotlinCodeGenTask;
import org.pkl.gradle.task.ModulesTask;
import org.pkl.gradle.task.PkldocTask;
import org.pkl.gradle.task.ProjectPackageTask;
import org.pkl.gradle.task.ProjectResolveTask;
import org.pkl.gradle.task.TestTask;
import org.pkl.gradle.utils.PluginUtils;

@SuppressWarnings("unused")
public class PklPlugin implements Plugin<Project> {

  private static final String MIN_GRADLE_VERSION = "8.2";

  @Override
  public void apply(Project project) {

    if (GradleVersion.current().compareTo(GradleVersion.version(MIN_GRADLE_VERSION)) < 0) {
      throw new GradleException(
          String.format("Plugin `org.pkl` requires Gradle %s or higher.", MIN_GRADLE_VERSION));
    }

    var extension = project.getExtensions().create("pkl", PklExtension.class);
    configureExtension(project, extension);
  }

  private void configureExtension(Project project, PklExtension extension) {
    configureEvalTasks(project, extension.getEvaluators());
    configureJavaCodeGenTasks(project, extension.getJavaCodeGenerators());
    configureKotlinCodeGenTasks(project, extension.getKotlinCodeGenerators());
    configurePkldocTasks(project, extension.getPkldocGenerators());
    configureTestTasks(project, extension.getTests());
    configureProjectPackageTasks(project, extension.getProject().getPackagers());
    configureProjectResolveTasks(project, extension.getProject().getResolvers());
    configureAnalyzeImportsTasks(project, extension.getAnalyzers().getImports());
  }

View on GitHub (pinned to f3efcbfc9b)