{"record":{"id":"8c8eb2a472b6e581","repo":"elastic/elasticsearch","slug":"system-property-bwc-throttle-maxparallelusages-m","errorCode":null,"errorMessage":"System property 'bwc.throttle.maxParallelUsages' must be >= 1","messagePattern":"System property 'bwc\\.throttle\\.maxParallelUsages' must be >= 1","errorType":"exception","errorClass":"GradleException","httpStatus":null,"severity":"error","filePath":"build-tools-internal/src/main/java/org/elasticsearch/gradle/internal/BwcSetupExtension.java","lineNumber":203,"sourceCode":"            ).map(paths -> paths.isEmpty() ? List.of() : List.of(\"-Dorg.gradle.java.installations.paths=\" + paths));\n            loggedExec.getArgs().addAll(jdkInstallationsArg);\n\n            loggedExec.getIndentingConsoleOutput().set(unreleasedVersionInfo.map(v -> v.version().toString()));\n\n            // We wanna have the option to throttle the parallel execution of the bwc tasks themselves\n            // e.g. for CI environments with limited resources or when running ci caching scripts\n            configureBwcThrottle(project, loggedExec);\n            configAction.execute(loggedExec);\n        });\n    }\n\n    private static void configureBwcThrottle(Project project, LoggedExec loggedExec) {\n        Provider<String> throttleProperty = project.getProviders().systemProperty(BWC_THROTTLE_MAX_PARALLEL_USAGES);\n        if (throttleProperty.isPresent()) {\n            try {\n                int maxParallelUsages = Integer.parseInt(throttleProperty.get());\n                if (maxParallelUsages < 1) {\n                    throw new GradleException(\"System property 'bwc.throttle.maxParallelUsages' must be >= 1\");\n                }\n                Provider<BwcThrottle> throttle = project.getGradle()\n                    .getSharedServices()\n                    .registerIfAbsent(\"bwcThrottle\", BwcThrottle.class, spec -> spec.getMaxParallelUsages().set(maxParallelUsages));\n\n                loggedExec.usesService(throttle);\n            } catch (NumberFormatException e) {\n                throw new GradleException(\"System property 'bwc.throttle.maxParallelUsages' must be an integer value\", e);\n            }\n        }\n    }\n\n    /** A convenience method for getting java home for a version of java and requiring that version for the given task to execute */\n    private static Provider<String> getJavaHome(ObjectFactory objectFactory, JavaToolchainService toolChainService, final int version) {\n        Property<JavaLanguageVersion> value = objectFactory.property(JavaLanguageVersion.class).value(JavaLanguageVersion.of(version));\n        return toolChainService.launcherFor(javaToolchainSpec -> javaToolchainSpec.getLanguageVersion().value(value))\n            .map(launcher -> launcher.getMetadata().getInstallationPath().getAsFile().getAbsolutePath());\n    }","sourceCodeStart":185,"sourceCodeEnd":221,"githubUrl":"https://github.com/elastic/elasticsearch/blob/db6a809a667c081ca1dc7500389d26975573215f/build-tools-internal/src/main/java/org/elasticsearch/gradle/internal/BwcSetupExtension.java#L185-L221","documentation":"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.","triggerScenarios":"Running the build with -Dbwc.throttle.maxParallelUsages=0 or a negative integer, e.g. ./gradlew bwcTest -Dbwc.throttle.maxParallelUsages=0.","commonSituations":"Attempting to disable the throttle by setting 0; CI script computing the value and underflowing; copy-paste from a different property that allowed 0.","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."],"exampleFix":"// before\n./gradlew bwcTest -Dbwc.throttle.maxParallelUsages=0\n// after\n./gradlew bwcTest -Dbwc.throttle.maxParallelUsages=1","handlingStrategy":"validation","validationCode":"String raw = System.getProperty(\"bwc.throttle.maxParallelUsages\");\nif (raw != null) {\n    int v = Integer.parseInt(raw);\n    if (v < 1) throw new GradleException(\"bwc.throttle.maxParallelUsages must be >= 1\");\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["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."],"tags":["gradle","bwc","throttle","build-tools"],"backgroundTag":null,"analyzedSha":"db6a809a667c081ca1dc7500389d26975573215f","analyzedAt":"2026-08-12T01:39:14.192Z","schemaVersion":2},"datasetVersion":"2026-08-13T09:17:06.757Z"}