elastic/elasticsearch · error · VerificationException

TransportVersion.fromName("{}") was used at {}, but lacks a

Error message

TransportVersion.fromName("{}") was used at {}, but lacks a transport version definition. If this is a new transport version, run './gradlew generateTransportVersion'.

What it means

Thrown by ValidateTransportVersionReferencesTask, which scans a generated list of every TransportVersion.fromName("...") call site in the source tree and confirms each referenced name has a corresponding transport-version definition. A missing definition means the source references a version name that the versioning machinery does not know about, so bwc serialization would fail at runtime.

Source

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

    @InputDirectory
    @Optional
    @PathSensitive(PathSensitivity.RELATIVE)
    public Path getDefinitionsDir() {
        return getTransportResources().get().getDefinitionsDir();
    }

    @InputFile
    @PathSensitive(PathSensitivity.RELATIVE)
    public abstract RegularFileProperty getReferencesFile();

    @TaskAction
    public void validateTransportVersions() throws IOException {
        Path namesFile = getReferencesFile().get().getAsFile().toPath();
        TransportVersionResourcesService resources = getTransportResources().get();

        for (var tvReference : TransportVersionReference.listFromFile(namesFile)) {
            if (resources.referableDefinitionExists(tvReference.name()) == false) {
                throw new VerificationException(
                    "TransportVersion.fromName(\""
                        + tvReference.name()
                        + "\") was used at "
                        + tvReference.location()
                        + ", but lacks a transport version definition. "
                        + "If this is a new transport version, run './gradlew generateTransportVersion'."
                );
            }
        }
    }
}

View on GitHub (pinned to db6a809a66)

Solutions

1. Run './gradlew generateTransportVersion' from the repo root — this creates the definition and upper-bound entries the reference needs.
2. If the reference is itself the mistake (typo or leftover from a refactor), correct or remove the TransportVersion.fromName(...) call at the location printed in the message.
3. Commit the newly generated resource files alongside the source change so the validate task passes on CI.

Example fix

// before
private static final TransportVersion FOO = TransportVersion.fromName("foo_bar_added");
// missing definition -> run:
//   ./gradlew generateTransportVersion
// after: definition + upper bound files generated and committed

// After adding any TransportVersion.fromName("...") call, run:
//   ./gradlew generateTransportVersion
// then commit the generated resource files before running the validate task.

When it happens

Trigger: A developer adds TransportVersion.fromName("my_new_thing") in server/module code but never ran './gradlew generateTransportVersion' to emit the definition and upper-bound resource files. The validation task reads the references file (collected by a codegen/scan task) and fails the build on the first unknown name.

Common situations: New wire-format change introduced without regenerating version resources; a typo in the version name string; rebasing onto a branch where the referenced definition was removed or renamed; CI running the validate task before the generate task in a dirty tree.

Related errors

• Version {} already exists in TransportVersions.csv with tran
• Invalid tag format [{l}]
• Output file not specified
• No version ids found in {javaVersionsFile}
• Invalid version format: '{s}'. Should be {pattern}

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