elastic/elasticsearch · error · IllegalArgumentException

Invalid increment {}, must be no larger than 1000

Error message

Invalid increment {}, must be no larger than 1000

What it means

IllegalArgumentException when the increment value exceeds 1000. The task caps increments to keep transport-version ids from jumping more than one base boundary (minors use 1000, patches use 1), so values above 1000 are rejected.

Source

Thrown at build-tools-internal/src/main/java/org/elasticsearch/gradle/internal/transport/AbstractGenerateTransportVersionDefinitionTask.java:116

        );
        // (Re)write the definition file.
        resources.writeDefinition(new TransportVersionDefinition(targetDefinitionName, ids, true));
    }

    private List<TransportVersionId> updateUpperBounds(
        TransportVersionResourcesService resources,
        List<TransportVersionUpperBound> existingUpperBounds,
        Set<String> targetUpperBoundNames,
        Map<Integer, List<IdAndDefinition>> idsByBase,
        String definitionName
    ) throws IOException {
        String currentUpperBoundName = getCurrentUpperBoundName().get();
        int increment = getIncrement().get();
        if (increment <= 0) {
            throw new IllegalArgumentException("Invalid increment " + increment + ", must be a positive integer");
        }
        if (increment > 1000) {
            throw new IllegalArgumentException("Invalid increment " + increment + ", must be no larger than 1000");
        }
        List<TransportVersionId> ids = new ArrayList<>();

        TransportVersionDefinition existingDefinition = resources.getReferableDefinitionFromGitBase(definitionName);
        for (TransportVersionUpperBound existingUpperBound : existingUpperBounds) {
            String upperBoundName = existingUpperBound.name();

            if (targetUpperBoundNames.contains(upperBoundName)) {
                // Case: targeting this upper bound, find an existing id if it exists
                TransportVersionId targetId = maybeGetExistingId(existingUpperBound, existingDefinition, definitionName);
                if (targetId == null) {
                    // Case: an id doesn't yet exist for this upper bound, so create one
                    int targetIncrement = upperBoundName.equals(currentUpperBoundName) ? increment : 1;
                    targetId = createTargetId(existingUpperBound, targetIncrement);
                    var newUpperBound = new TransportVersionUpperBound(upperBoundName, definitionName, targetId);
                    writeUpperBound(resources, newUpperBound);
                }
                ids.add(targetId);

View on GitHub (pinned to db6a809a66)

Solutions

1. Use a value <= 1000; for minor bumps the canonical value is 1000 and for patches it is 1.
2. Re-check the wrapper script or CI job that computes the increment.
3. If a larger jump is genuinely needed, revisit the transport-version scheme rather than raising the cap.

Example fix

// before: ./gradlew generateTransportVersionDefinition --increment=5000
// after:  ./gradlew generateTransportVersionDefinition --increment=1000

int increment = getIncrement().get();
if (increment > 1000) {
    throw new IllegalArgumentException("--increment must be <= 1000 (use 1000 for minors, 1 for patches), got " + increment);
}

When it happens

Trigger: getIncrement().get() returns a value > 1000, typically from a typo or a script computing the increment incorrectly.

Common situations: Passing --increment=10000 by mistake; treating a minor bump (which should be 1000) as a larger custom value; off-by orders-of-magnitude typo.

Related errors

• Invalid increment {}, must be a positive integer
• Missing upper bounds files for branches {}, known branches a
• classname is a required setting for esplugin
• classname is a forbidden for stable esplugin
• invalid deploymentTarget '{}', expected one of {}

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