elastic/elasticsearch · error · IllegalArgumentException

Missing upper bounds files for branches {}, known branches a

Error message

Missing upper bounds files for branches {}, known branches are {}

What it means

IllegalArgumentException from getTargetUpperBoundNames() when one or more requested target/backport branch names do not have corresponding upper-bound files in the upstream set. The message lists the missing branches and the known ones so the mismatch is obvious.

Source

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

        List<TransportVersionUpperBound> upstreamUpperBounds,
        String targetDefinitionName
    ) throws IOException {
        Set<String> targetUpperBoundNames = new HashSet<>();
        targetUpperBoundNames.add(getCurrentUpperBoundName().get());
        if (getBackportBranches().isPresent()) {
            targetUpperBoundNames.addAll(List.of(getBackportBranches().get().split(",")));
        }

        Set<String> missingBranches = new HashSet<>(targetUpperBoundNames);
        List<String> knownUpperBoundNames = new ArrayList<>();
        for (TransportVersionUpperBound upperBound : upstreamUpperBounds) {
            knownUpperBoundNames.add(upperBound.name());
            missingBranches.remove(upperBound.name());
        }
        if (missingBranches.isEmpty() == false) {
            List<String> sortedMissing = missingBranches.stream().sorted().toList();
            List<String> sortedKnown = knownUpperBoundNames.stream().sorted().toList();
            throw new IllegalArgumentException(
                "Missing upper bounds files for branches " + sortedMissing + ", known branches are " + sortedKnown
            );
        }

        return targetUpperBoundNames;
    }

    private void resetAllUpperBounds(TransportVersionResourcesService resources, Map<Integer, List<IdAndDefinition>> idsByBase)
        throws IOException {
        for (String upperBoundName : resources.getChangedUpperBoundNames()) {
            TransportVersionUpperBound upstreamUpperBound = resources.getUpperBoundFromGitBase(upperBoundName);
            resetUpperBound(resources, upstreamUpperBound, idsByBase, null);
        }
    }

    private void resetUpperBound(
        TransportVersionResourcesService resources,
        TransportVersionUpperBound upperBound,

View on GitHub (pinned to db6a809a66)

Solutions

1. Compare the missing-branches list in the message against the known-branches list and correct typos.
2. Ensure each named branch has its upper-bound CSV committed upstream.
3. Update your local transport-resources directory from the base branch.

Example fix

// before: --backport-branches=9.1,8.19  (9.1 unknown)
// after:  --backport-branches=9.x,8.19

Set<String> known = upstreamUpperBounds.stream().map(TransportVersionUpperBound::name).collect(Collectors.toSet());
List<String> unknown = targetUpperBoundNames.stream().filter(n -> !known.contains(n)).sorted().toList();
if (!unknown.isEmpty()) {
    throw new IllegalArgumentException("Unknown backport branches " + unknown + "; known: " + new TreeSet<>(known));
}

When it happens

Trigger: The --backport-branches option (or the current branch) names branches whose upper-bound CSVs are not present among upstreamUpperBounds.

Common situations: Typo in a --backport-branches value (e.g. '9.1' vs '9.x'); referencing a branch whose upper-bound file was never created; the upstream resources dir is stale relative to the named branches.

Related errors

• Invalid increment {}, must be a positive integer
• Invalid increment {}, must be no larger than 1000
• 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/5cfed771ee8586b0. Report an issue: GitHub.