gradle/gradle · error · InvalidRunnerConfigurationException

Debug mode is not allowed when environment variables are spe

Error message

Debug mode is not allowed when environment variables are specified. Debug mode runs 'in process' but we need to fork a separate process to pass environment variables. To run with debug mode, please remove environment variables.

What it means

Error "Debug mode is not allowed when environment variables are specified. Debug mode runs 'in process' but we need to fork a separate process to pass environment variables. To run with debug mode, please remove environment variables." thrown in gradle/gradle.

Source

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

        if (output != null && !output.isEmpty()) {
            message.append(lineBreak);
            message.append(lineBreak);
            message.append("Output:");
            message.append(lineBreak);
            message.append(output);
        }

        return message.toString();
    }

    private BuildResult run(Action<GradleExecutionResult> resultVerification) {
        if (projectDirectory == null) {
            throw new InvalidRunnerConfigurationException("Please specify a project directory before executing the build");
        }

        if (environment != null && debug) {
            throw new InvalidRunnerConfigurationException("Debug mode is not allowed when environment variables are specified. " +
                "Debug mode runs 'in process' but we need to fork a separate process to pass environment variables. " +
                "To run with debug mode, please remove environment variables.");
        }

        File testKitDir = createTestKitDir(testKitDirProvider);

        GradleProvider effectiveDistribution = gradleProvider == null ? findGradleInstallFromGradleRunner() : gradleProvider;

        List<String> effectiveArguments = new ArrayList<>();
        Map<String, String> effectiveEnvironment = new HashMap<>();

        if (OperatingSystem.current().isWindows()) {
            // When using file system watching in Windows tests it becomes harder to delete the project directory,
            // since file system watching on Windows adds a lock on the watched directory, which is currently the project directory.
            // After deleting the contents of the watched directory, Gradle will stop watching the directory and release the file lock.
            // That may require a retry to delete the watched directory.
            // To avoid those problems for TestKit tests on Windows, we disable file system watching there.
            effectiveArguments.add("-D" + StartParameterBuildOptions.WatchFileSystemOption.GRADLE_PROPERTY + "=false");

View on GitHub (pinned to 534f27719b)

Solutions

1. Either remove the environment variables passed via withEnvironment(...) or disable debug mode via withDebug(false); debug mode runs in-process and cannot pass environment variables to a forked process.

When it happens

Trigger: Thrown at platforms/extensibility/test-kit/src/main/java/org/gradle/testkit/runner/internal/DefaultGradleRunner.java:328 when the library encounters an invalid state.

Common situations: Triggered when withDebug(true) is combined with withEnvironment(...) on GradleRunner. Debug runs the build in-process and cannot propagate custom environment variables; remove the environment variables or disable debug mode.

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