gradle/gradle · error · IllegalArgumentException

The specified %s does not appear to contain a Gradle distrib

Error message

The specified %s does not appear to contain a Gradle distribution.

What it means

The third validation in InstalledDistribution: the Tooling API loads the provider classpath from the lib/ directory of the target distribution (a cross-Gradle-version contract). If gradleHomeDir exists and is a directory but has no lib/ subdirectory, the path is not a Gradle distribution layout and this IllegalArgumentException is thrown ('The specified ... does not appear to contain a Gradle distribution.').

Source

Thrown at platforms/ide/tooling-api/src/main/java/org/gradle/tooling/internal/consumer/DistributionFactory.java:160

        @Override
        public String getDisplayName() {
            return displayName;
        }

        @Override
        public ClassPath getToolingImplementationClasspath(ProgressLoggerFactory progressLoggerFactory, InternalBuildProgressListener progressListener, ConnectionParameters connectionParameters, BuildCancellationToken cancellationToken) {
            if (!gradleHomeDir.exists()) {
                throw new IllegalArgumentException(String.format("The specified %s does not exist.", locationDisplayName));
            }
            if (!gradleHomeDir.isDirectory()) {
                throw new IllegalArgumentException(String.format("The specified %s is not a directory.", locationDisplayName));
            }
            // The lib directory implements a cross-gradle-version contract, where the
            // TAPI consumer will load the TAPI provider classpath from the
            // `lib` directory of the target gradle distribution.
            File libDir = new File(gradleHomeDir, "lib");
            if (!libDir.isDirectory()) {
                throw new IllegalArgumentException(String.format("The specified %s does not appear to contain a Gradle distribution.", locationDisplayName));
            }
            File[] files = libDir.listFiles(new FileFilter() {
                @Override
                public boolean accept(File file) {
                    return hasExtension(file, ".jar");
                }
            });
            // Make sure file order is always consistent
            Arrays.sort(files);
            return DefaultClassPath.of(files);
        }
    }

}

View on GitHub (pinned to 534f27719b)

Solutions

Point useInstallation() at a complete Gradle distribution: the directory that directly contains bin/ and lib/ (e.g. /opt/gradle-8.7 from gradle-8.7-bin.zip).
Re-download and fully extract the distribution, then verify ls <dir>/lib lists the gradle-*.jar files.
If you meant the wrapper-managed distribution, remove useInstallation and let the wrapper resolve it instead.

Example fix

# before
connector.useInstallation(new File("/opt"));            # contains gradle-8.7/ but no lib/
connector.useInstallation(new File("/opt/gradle-8.7/lib")); # wrong level

# after
connector.useInstallation(new File("/opt/gradle-8.7"));    # contains bin/ and lib/

Defensive patterns

Strategy: validation

Validate before calling

static boolean looksLikeGradleDistribution(Path dir) throws IOException {
    Path lib = dir.resolve("lib");
    if (!Files.isDirectory(lib)) return false;
    try (Stream<Path> jars = Files.list(lib)) {
        return jars.anyMatch(p -> p.toString().endsWith(".jar"));
    }
}
// before useInstallation(dir): if (!looksLikeGradleDistribution(dir)) throw new ConfigurationError(dir + " has no lib/ with jars - not a Gradle distribution");

Prevention

After any custom download/extract step, assert <install>/lib contains gradle-*.jar before using the install.
Point useInstallation at the directory directly containing bin/ and lib/, exactly one level above lib/.
Do not use GRADLE_USER_HOME, a source checkout, or partial extractions as an installation.

When it happens

Trigger: useInstallation(...) pointed at a directory that is not a distribution: a git clone of gradle/gradle, a partially extracted archive, or the parent folder one level above/below the real install root (e.g. /opt instead of /opt/gradle-8.7).

Common situations: Custom download logic that extracts only part of the ZIP; wrappers that store distributions in non-standard layouts; pointing at GRADLE_USER_HOME (~/.gradle) which contains caches but no lib/.

Related errors

AI-assisted analysis of gradle/gradle@534f27719b (2026-08-22). Data as JSON: /api/errors/91e234436611e511. Report an issue: GitHub.