What causes "System property 'bwc.throttle.maxParallelUsages' must be >= 1" in elastic/elasticsearch?

Set the property to a value >= 1, e.g. -Dbwc.throttle.maxParallelUsages=1.

elastic/elasticsearch · error · GradleException

System property 'bwc.throttle.maxParallelUsages' must be >=

Error message

System property 'bwc.throttle.maxParallelUsages' must be >= 1

What it means

Thrown by BwcSetupExtension.configureBwcThrottle when the system property bwc.throttle.maxParallelUsages is set to an integer below 1. The throttle is a Gradle BuildService (BwcThrottle) that limits concurrent backward-compatibility build executions; zero or negative parallelism is meaningless.

Source

Thrown at build-tools-internal/src/main/java/org/elasticsearch/gradle/internal/BwcSetupExtension.java:203

            ).map(paths -> paths.isEmpty() ? List.of() : List.of("-Dorg.gradle.java.installations.paths=" + paths));
            loggedExec.getArgs().addAll(jdkInstallationsArg);

            loggedExec.getIndentingConsoleOutput().set(unreleasedVersionInfo.map(v -> v.version().toString()));

            // We wanna have the option to throttle the parallel execution of the bwc tasks themselves
            // e.g. for CI environments with limited resources or when running ci caching scripts
            configureBwcThrottle(project, loggedExec);
            configAction.execute(loggedExec);
        });
    }

    private static void configureBwcThrottle(Project project, LoggedExec loggedExec) {
        Provider<String> throttleProperty = project.getProviders().systemProperty(BWC_THROTTLE_MAX_PARALLEL_USAGES);
        if (throttleProperty.isPresent()) {
            try {
                int maxParallelUsages = Integer.parseInt(throttleProperty.get());
                if (maxParallelUsages < 1) {
                    throw new GradleException("System property 'bwc.throttle.maxParallelUsages' must be >= 1");
                }
                Provider<BwcThrottle> throttle = project.getGradle()
                    .getSharedServices()
                    .registerIfAbsent("bwcThrottle", BwcThrottle.class, spec -> spec.getMaxParallelUsages().set(maxParallelUsages));

                loggedExec.usesService(throttle);
            } catch (NumberFormatException e) {
                throw new GradleException("System property 'bwc.throttle.maxParallelUsages' must be an integer value", e);
            }
        }
    }

    /** A convenience method for getting java home for a version of java and requiring that version for the given task to execute */
    private static Provider<String> getJavaHome(ObjectFactory objectFactory, JavaToolchainService toolChainService, final int version) {
        Property<JavaLanguageVersion> value = objectFactory.property(JavaLanguageVersion.class).value(JavaLanguageVersion.of(version));
        return toolChainService.launcherFor(javaToolchainSpec -> javaToolchainSpec.getLanguageVersion().value(value))
            .map(launcher -> launcher.getMetadata().getInstallationPath().getAsFile().getAbsolutePath());
    }

View on GitHub (pinned to db6a809a66)

Solutions

Set the property to a value >= 1, e.g. -Dbwc.throttle.maxParallelUsages=1.
Omit the property entirely to use the default unthrottled behaviour.
If the goal is to minimize parallelism, use 1 rather than 0.

Example fix

// before
./gradlew bwcTest -Dbwc.throttle.maxParallelUsages=0
// after
./gradlew bwcTest -Dbwc.throttle.maxParallelUsages=1

Defensive patterns

Strategy: validation

Validate before calling

String raw = System.getProperty("bwc.throttle.maxParallelUsages");
if (raw != null) {
    int v = Integer.parseInt(raw);
    if (v < 1) throw new GradleException("bwc.throttle.maxParallelUsages must be >= 1");
}

Prevention

Treat 0 as 'disable the property entirely' rather than a valid value.
Validate CI-injected numeric properties before passing them to the build.
Document the >= 1 constraint next to every mention of the property.

When it happens

Trigger: Running the build with -Dbwc.throttle.maxParallelUsages=0 or a negative integer, e.g. ./gradlew bwcTest -Dbwc.throttle.maxParallelUsages=0.

Common situations: Attempting to disable the throttle by setting 0; CI script computing the value and underflowing; copy-paste from a different property that allowed 0.

Related errors

AI-assisted analysis of elastic/elasticsearch@db6a809a66 (2026-08-12). Data as JSON: /api/errors/8c8eb2a472b6e581. Report an issue: GitHub.