elastic/elasticsearch · error · IllegalArgumentException

Transport version generation cannot run on release branches

Error message

Transport version generation cannot run on release branches

What it means

IllegalArgumentException from GenerateTransportVersionDefinitionTask.runGeneration() when the task detects it is executing on a release branch. Transport-version definition generation is only permitted on main; release branches consume the versions already produced upstream.

Source

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

    @Option(option = "name", description = "The name of the Transport Version definition, e.g. --name=my_new_tv")
    public abstract Property<String> getDefinitionName();

    @Input
    @Optional
    @Option(
        option = "backport-branches",
        description = "The branches this definition will be backported to, e.g. --backport-branches=9.1,8.19"
    )
    public abstract Property<String> getBackportBranches();

    @Override
    protected void runGeneration(
        TransportVersionResourcesService resources,
        List<TransportVersionUpperBound> upstreamUpperBounds,
        boolean onReleaseBranch
    ) throws IOException {
        if (onReleaseBranch) {
            throw new IllegalArgumentException("Transport version generation cannot run on release branches");
        }

        Set<String> referencedNames = TransportVersionReference.collectNames(getReferencesFiles());
        Set<String> changedDefinitionNames = resources.getChangedReferableDefinitionNames();
        String targetDefinitionName = getTargetDefinitionName(resources, referencedNames, changedDefinitionNames);

        // First check for any unused definitions. This later generation to not get confused by a definition that can't be used.
        removeUnusedNamedDefinitions(resources, referencedNames, changedDefinitionNames);

        Map<Integer, List<IdAndDefinition>> idsByBase = resources.getIdsByBase();
        if (targetDefinitionName.isEmpty()) {
            getLogger().lifecycle("No transport version name detected, resetting upper bounds");
            resetAllUpperBounds(resources, idsByBase);
        } else {
            generateTransportVersionDefinition(resources, targetDefinitionName, upstreamUpperBounds, idsByBase);
        }
    }

View on GitHub (pinned to db6a809a66)

Solutions

1. Switch to main before running the generate-transport-version-definition task.
2. If you are on a release branch intentionally, you do not need to run this task - use UpdateTransportVersionsCSVTask instead.
3. Fix the branch-detection configuration if it is mislabelling main as a release branch.

Example fix

// before: on branch 9.x, running generateTransportVersionDefinition
// after:  git switch main && ./gradlew generateTransportVersionDefinition

// Branch guard before invoking the task
String branch = gitCurrentBranch();
if (isReleaseBranch(branch)) {
    throw new IllegalStateException("Refusing to run generate task on release branch " + branch + "; switch to main");
}

static boolean isReleaseBranch(String b) {
    return b != null && b.matches("\\d+\\.x");
}

When it happens

Trigger: The task is invoked with onReleaseBranch == true, which is set by the task's branch-detection logic based on the current git branch name matching a release-branch pattern.

Common situations: Running the generate task while checked out on a 9.x / 8.x release branch; CI misclassifying the current branch; invoking the task from a release-branch build script by mistake.

Related errors

• Missing upper bound {} for release version {}
• Missing upper bound {} for stack version {}
• Invalid increment {}, must be a positive integer
• Invalid increment {}, must be no larger than 1000
• Could not find base id: {}

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