elastic/elasticsearch · error · GradleException

System property 'bwc.throttle.maxParallelUsages' must be an

Error message

System property 'bwc.throttle.maxParallelUsages' must be an integer value

What it means

Thrown by BwcSetupExtension.configureBwcThrottle when the system property bwc.throttle.maxParallelUsages cannot be parsed as an int (NumberFormatException). It wraps the original parse exception so the user sees the cause.

Source

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

            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());
    }

    /**
     * A {@link ValueSource} that lists all JDK installations provisioned by the Gradle toolchain resolver
     * under the {@code jdks/} subdirectory of the Gradle user home directory.
     *
     * <p>The resolver stores each JDK two levels deep:
     * {@code jdks/<vendor-version-arch-os>/<jdk-bundle>/}.  This source collects every
     * second-level directory (the actual JDK bundles) and returns them as a comma-separated

View on GitHub (pinned to db6a809a66)

Solutions

Provide a valid integer, e.g. -Dbwc.throttle.maxParallelUsages=2.
Omit the property to skip throttle configuration.
Check CI/shell quoting around the value.

Example fix

// before
./gradlew bwcTest -Dbwc.throttle.maxParallelUsages=two
// after
./gradlew bwcTest -Dbwc.throttle.maxParallelUsages=2

Defensive patterns

Strategy: validation

Validate before calling

String raw = System.getProperty("bwc.throttle.maxParallelUsages");
if (raw != null) {
    Integer.parseInt(raw); // throws NumberFormatException if invalid
}

Try / catch

try {
    Integer.parseInt(throttleProperty.get());
} catch (NumberFormatException e) {
    throw new GradleException("bwc.throttle.maxParallelUsages must be an integer value", e);
}

Prevention

Quote numeric system properties correctly in shell wrappers.
Validate CI template variables that feed this property.
Provide a sane default and omit the property when unsure.

When it happens

Trigger: Running the build with -Dbwc.throttle.maxParallelUsages=abc or any non-integer token.

Common situations: Typo in the property value; CI templating that injects an empty or non-numeric string; quoting error in a shell wrapper.

Related errors

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