elastic/elasticsearch · error · VerificationException

Transport version definition file [{}] {}

Error message

Transport version definition file [{}] {}

What it means

Generic wrapper thrown by throwDefinitionFailure for any transport-version *definition* file failing a structural check. The trailing message pinpoints the violation: 'contains id X already defined in [...]' (duplicate ID across files), 'was added but no corresponding upper bounds file was changed' (definition without an upper bound), or 'has primary id X which is more than maximum increment 1000...' / '...is not present in any upper bounds files'. The file path in brackets identifies the offending definition file.

Source

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

        TransportVersionResourcesService resources,
        Map<String, TransportVersionDefinition> referableDefinitions,
        Map<String, TransportVersionUpperBound> upperBounds
    ) {
        Set<String> changedDefinitionNames = resources.getChangedReferableDefinitionNames();
        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. Read the trailing message: if it mentions a missing upper bound, create/commit the corresponding upper-bounds file for that definition name.
2. If it reports a duplicate ID, renumber the new definition's ID to a free value (or run './gradlew generateTransportVersion' to allocate).
3. If it reports the highest ID is unreferenced or exceeds the 1000 increment, add an upper-bound entry pointing at that definition or correct the ID allocation.

Example fix

// before: definition 'foo' committed, but no upper-bounds file references it
//   -> 'Transport version definition file [...] was added but no corresponding upper bounds file was changed'
// after: add an upper-bounds entry naming 'foo' in the same PR

// PR checklist for a new transport version definition:
//   1. definition file added
//   2. upper-bounds file referencing the same definition name added in the same commit
//   3. ID is unique across all definition files
//   4. './gradlew generateTransportVersion' + validate task both pass

When it happens

Trigger: Adding a new definition file without a matching upper-bounds file; two definition files claiming the same numeric ID; the highest-ID definition not referenced by any upper bound; a primary ID jumping more than 1000 from the previous highest.

Common situations: PR adds a transport version but forgets the upper-bound stub; cherry-picking a definition onto a branch that already allocated that ID; copy-pasting a definition file and forgetting to bump the ID.

Related errors

• Transport version base id {} is missing patch ids between {}
• Transport version upper bound 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/a54c2ef4a1c87ece. Report an issue: GitHub.