elastic/elasticsearch · error · VerificationException

Transport version upper bound file [{}] {}

Error message

Transport version upper bound file [{}] {}

What it means

Generic wrapper thrown by throwUpperBoundFailure for any transport-version *upper bound* file failing a structural check. The trailing message identifies the issue, e.g. 'modifies base id from X to Y' when an upper bound for a patch (patch != 0) is changed to point at a different base ID than the existing one — base IDs are immutable once a patch exists. The file path in brackets names the offending upper-bound file.

Source

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

        for (String name : changedDefinitionNames) {
            TransportVersionDefinition definition = referableDefinitions.get(name);
            if (definition != null && resources.getReferableDefinitionFromGitBase(name) == null) {
                boolean hasUpperBound = upperBounds.values().stream().anyMatch(ub -> ub.definitionName().equals(name));
                if (hasUpperBound == false) {
                    throwDefinitionFailure(definition, "was added but no corresponding upper bounds file was changed");
                }
            }
        }
    }

    private void throwDefinitionFailure(TransportVersionDefinition definition, String message) {
        Path relativePath = getResources().get().getDefinitionPath(definition);
        throw new VerificationException("Transport version definition file [" + relativePath + "] " + message);
    }

    private void throwUpperBoundFailure(TransportVersionUpperBound upperBound, String message) {
        Path relativePath = getResources().get().getUpperBoundRepositoryPath(upperBound);
        throw new VerificationException("Transport version upper bound file [" + relativePath + "] " + message);
    }
}

View on GitHub (pinned to db6a809a66)

Solutions

1. Restore the original base ID in the named upper-bound file (git checkout the file if the change was unintentional).
2. If a new base ID is genuinely required, create a NEW upper-bound entry/definition rather than mutating a released patch bound.
3. Rerun the validate task to confirm.

Example fix

// before: upper-bound file for v9.0.1 changed base from 8800000 to 8800100
//   -> 'Transport version upper bound file [...] modifies base id from 8800000 to 8800100'
// after: git checkout -- <upper-bound-file>  (revert); add a new bound for the new base instead

// For any existing upper bound whose patch() != 0, the base ID must equal the value in git:
//   existingBase == upperBound.definitionId().base()  (do not mutate)

When it happens

Trigger: Editing an existing upper-bound file so its definitionId().base() no longer matches the base recorded in git for that bound, while patch() != 0; re-pointing an upper bound at a different definition after release.

Common situations: Backport swaps an upper bound to a different definition; hand-editing the upper-bound resource file; rebasing across branches where the base allocation differs.

Related errors

• Transport version base id {} is missing patch ids between {}
• Transport version definition file [{}] {}
• Invalid version format: '{s}'. Should be {pattern}
• Version {} already exists in TransportVersions.csv with tran
• TransportVersion.fromName("{}") was used at {}, but lacks a

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