gradle/gradle · error · InvalidRunnerConfigurationException

Unable to create test kit directory: {}

Error message

Unable to create test kit directory: {}

What it means

Gradle TestKit needs a scratch directory (the "test kit dir") to store daemon logs and helper jars before it can launch a test build. DefaultGradleRunner.createTestKitDir() reuses the directory if it exists and is writable, rejects a non-directory path, and only as a last resort calls dir.mkdirs(). This InvalidRunnerConfigurationException means the directory does not exist and the filesystem refused to create it (mkdirs() failed and a follow-up isDirectory() check also failed).

Source

Thrown at platforms/extensibility/test-kit/src/main/java/org/gradle/testkit/runner/internal/DefaultGradleRunner.java:399

            execResult.getOutputSource(),
            execResult.getTasks(),
            execResult.getConfigurationCacheOutcome()
        );
    }

    private File createTestKitDir(TestKitDirProvider testKitDirProvider) {
        File dir = testKitDirProvider.getDir();
        if (dir.isDirectory()) {
            if (!dir.canWrite()) {
                throw new InvalidRunnerConfigurationException("Unable to write to test kit directory: " + dir.getAbsolutePath());
            }
            return dir;
        } else if (dir.exists() && !dir.isDirectory()) {
            throw new InvalidRunnerConfigurationException("Unable to use non-directory as test kit directory: " + dir.getAbsolutePath());
        } else if (dir.mkdirs() || dir.isDirectory()) {
            return dir;
        } else {
            throw new InvalidRunnerConfigurationException("Unable to create test kit directory: " + dir.getAbsolutePath());
        }
    }

    private static GradleProvider findGradleInstallFromGradleRunner() {
        GradleInstallation gradleInstallation = CurrentGradleInstallation.get();
        if (gradleInstallation == null) {
            String messagePrefix = "Could not find a Gradle installation to use based on the location of the GradleRunner class";
            try {
                File classpathForClass = ClasspathUtil.getClasspathForClass(GradleRunner.class);
                messagePrefix += ": " + classpathForClass.getAbsolutePath();
            } catch (Exception ignore) {
                // ignore
            }
            throw new InvalidRunnerConfigurationException(messagePrefix + ". Please specify a Gradle runtime to use via GradleRunner.withGradleVersion() or similar.");
        }
        return GradleProvider.installation(gradleInstallation.getGradleHome());
    }

View on GitHub (pinned to 534f27719b)

Solutions

1. Check the path printed in the message: verify every parent directory exists, is a directory, and is writable; confirm no regular file sits in the path
2. Fix the environment: free disk space (df -h), remount the volume read-write, or chmod the parent directory
3. Point TestKit somewhere writable: GradleRunner.create().withTestKitDir(new File(System.getProperty("java.io.tmpdir"), "test-kit"))
4. If a stale file or lock occupies the dir, remove it: rm -rf <dir> and rerun the test

Example fix

// before
GradleRunner.create()
    .withProjectDir(projectDir)
    .withArguments("build")
    .build(); // fails when the default test-kit dir cannot be created

// after
GradleRunner.create()
    .withProjectDir(projectDir)
    .withTestKitDir(new File(System.getProperty("java.io.tmpdir"), "my-test-kit"))
    .withArguments("build")
    .build();

File testKitDir = new File(System.getProperty("user.home"), ".gradle/test-kit");
if (testKitDir.isDirectory() && !testKitDir.canWrite()) {
    throw new IllegalStateException("Test kit dir not writable: " + testKitDir);
}
File probe = testKitDir;
while (probe != null && !probe.exists()) { probe = probe.getParentFile(); }
if (probe != null && !probe.isDirectory()) {
    throw new IllegalStateException("A non-directory blocks the path: " + probe);
}
if (!testKitDir.exists() && !testKitDir.mkdirs()) {
    throw new IllegalStateException("Cannot create test kit dir: " + testKitDir);
}

try {
    runner.build();
} catch (InvalidRunnerConfigurationException e) {
    if (e.getMessage() != null && e.getMessage().startsWith("Unable to create test kit directory")) {
        runner = runner.withTestKitDir(new File(System.getProperty("java.io.tmpdir"), "test-kit"));
        runner.build(); // retry once with a known-writable dir
    } else {
        throw e;
    }
}

When it happens

Trigger: Running GradleRunner.build() with a test kit dir (default GRADLE_USER_HOME-based location, the TEST_KIT_DIR env var, or a dir passed via withTestKitDir(...)) that cannot be created: a parent path component is a regular file, the user lacks write permission on a parent directory, the volume is read-only, or the disk is full.

Common situations: CI containers with a read-only or non-writable GRADLE_USER_HOME; a stray regular file occupying a parent path such as ~/.gradle/test-kit; Docker read-only mounts or macOS sandboxing; full build-agent disks.

Related errors

• Failed to create directory %s.
• Failed to create class directory %s.
• Could not make {} executable on a filesystem without POSIX s
• Failed to create install parent directory: {}
• Unable to create provisioned.ok file

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