{"record":{"id":"a54c2ef4a1c87ece","repo":"elastic/elasticsearch","slug":"transport-version-definition-file","errorCode":null,"errorMessage":"Transport version definition file [{}] {}","messagePattern":"Transport version definition file \\[(.+?)\\] (.+?)","errorType":"exception","errorClass":"VerificationException","httpStatus":null,"severity":"error","filePath":"build-tools-internal/src/main/java/org/elasticsearch/gradle/internal/transport/ValidateTransportVersionResourcesTask.java","lineNumber":365,"sourceCode":"        TransportVersionResourcesService resources,\n        Map<String, TransportVersionDefinition> referableDefinitions,\n        Map<String, TransportVersionUpperBound> upperBounds\n    ) {\n        Set<String> changedDefinitionNames = resources.getChangedReferableDefinitionNames();\n        for (String name : changedDefinitionNames) {\n            TransportVersionDefinition definition = referableDefinitions.get(name);\n            if (definition != null && resources.getReferableDefinitionFromGitBase(name) == null) {\n                boolean hasUpperBound = upperBounds.values().stream().anyMatch(ub -> ub.definitionName().equals(name));\n                if (hasUpperBound == false) {\n                    throwDefinitionFailure(definition, \"was added but no corresponding upper bounds file was changed\");\n                }\n            }\n        }\n    }\n\n    private void throwDefinitionFailure(TransportVersionDefinition definition, String message) {\n        Path relativePath = getResources().get().getDefinitionPath(definition);\n        throw new VerificationException(\"Transport version definition file [\" + relativePath + \"] \" + message);\n    }\n\n    private void throwUpperBoundFailure(TransportVersionUpperBound upperBound, String message) {\n        Path relativePath = getResources().get().getUpperBoundRepositoryPath(upperBound);\n        throw new VerificationException(\"Transport version upper bound file [\" + relativePath + \"] \" + message);\n    }\n}\n","sourceCodeStart":347,"sourceCodeEnd":373,"githubUrl":"https://github.com/elastic/elasticsearch/blob/db6a809a667c081ca1dc7500389d26975573215f/build-tools-internal/src/main/java/org/elasticsearch/gradle/internal/transport/ValidateTransportVersionResourcesTask.java#L347-L373","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Read the trailing message: if it mentions a missing upper bound, create/commit the corresponding upper-bounds file for that definition name.","If it reports a duplicate ID, renumber the new definition's ID to a free value (or run './gradlew generateTransportVersion' to allocate).","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."],"exampleFix":"// before: definition 'foo' committed, but no upper-bounds file references it\n//   -> 'Transport version definition file [...] was added but no corresponding upper bounds file was changed'\n// after: add an upper-bounds entry naming 'foo' in the same PR","handlingStrategy":"validation","validationCode":"// PR checklist for a new transport version definition:\n//   1. definition file added\n//   2. upper-bounds file referencing the same definition name added in the same commit\n//   3. ID is unique across all definition files\n//   4. './gradlew generateTransportVersion' + validate task both pass","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Always pair a new definition file with its upper-bound entry in the same change.","Never reuse a numeric ID across definition files.","Run the validate task locally before pushing."],"tags":["build","gradle","transport-version","validation","definition-files"],"analyzedSha":"db6a809a667c081ca1dc7500389d26975573215f","analyzedAt":"2026-08-12T01:39:14.192Z","schemaVersion":2},"datasetVersion":"2026-08-12T08:17:17.861Z"}