What causes "Invalid increment {}, must be a positive integer" in elastic/elasticsearch?

Pass a positive integer for --increment (e.g. --increment=1).

elastic/elasticsearch · error · IllegalArgumentException

Invalid increment {}, must be a positive integer

Error message

Invalid increment {}, must be a positive integer

What it means

IllegalArgumentException from updateUpperBounds() when the increment value configured for transport-version generation is zero or negative. The task requires a strictly positive integer increment.

Source

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

            targetUpperBoundNames,
            idsByBase,
            targetDefinitionName
        );
        // (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);

View on GitHub (pinned to db6a809a66)

Solutions

Pass a positive integer for --increment (e.g. --increment=1).
If invoking programmatically, set the increment property to a value > 0 before the task runs.
Check the task's default value configuration in build.gradle and supply a sane default.

Example fix

// before: ./gradlew generateTransportVersionDefinition --increment=0
// after:  ./gradlew generateTransportVersionDefinition --increment=1

Defensive patterns

Strategy: validation

Validate before calling

int increment = getIncrement().get();
if (increment <= 0) {
    throw new IllegalArgumentException("--increment must be a positive integer, got " + increment);
}

Prevention

Always pass --increment explicitly when running the task.
Default the increment property to a sensible positive value in build.gradle.
Validate CLI args in a wrapper script before delegating to Gradle.

When it happens

Trigger: getIncrement().get() returns a value <= 0 because the --increment option was omitted and defaulted to 0, or was explicitly passed as 0/negative.

Common situations: Running the generate-transport-version-definition task without setting --increment; a wrapper script passing an empty/defaulted value; misreading the option as 1-based vs 0-based.

Related errors

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