elastic/elasticsearch · error · IllegalStateException

Transport version base id {} is missing patch ids between {}

Error message

Transport version base id {} is missing patch ids between {} and {}

What it means

Thrown by validateBase in ValidateTransportVersionResourcesTask when density validation is enabled and the patch IDs within a single base ID are not perfectly contiguous. Transport version IDs are allocated densely (base + patch), so a gap between consecutive patch IDs signals a leaked/unused ID that breaks the compact allocation scheme.

Source

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

        }
    }

    private void validateBase(int base, List<IdAndDefinition> ids) {
        // TODO: switch this to a fully dense check once all existing transport versions have been migrated
        IdAndDefinition previous = ids.getLast();
        for (int ndx = ids.size() - 2; ndx >= 0; --ndx) {
            IdAndDefinition current = ids.get(ndx);

            if (previous.id().equals(current.id())) {
                Path existingDefinitionPath = getResources().get().getDefinitionPath(previous.definition());
                throwDefinitionFailure(
                    current.definition(),
                    "contains id " + current.id() + " already defined in [" + existingDefinitionPath + "]"
                );
            }

            if (getShouldValidateDensity().get() && previous.id().complete() - 1 != current.id().complete()) {
                throw new IllegalStateException(
                    "Transport version base id " + base + " is missing patch ids between " + current.id() + " and " + previous.id()
                );
            }
            previous = current;
        }
    }

    private void validatePrimaryIds(
        TransportVersionResourcesService resources,
        Map<String, TransportVersionUpperBound> upperBounds,
        Map<String, TransportVersionDefinition> allDefinitions
    ) {
        // first id is always the highest within a definition, and validated earlier
        // note the first element is actually the highest because the id comparator is in descending order
        var sortedDefinitions = allDefinitions.values().stream().sorted(Comparator.comparing(d -> d.ids().getFirst())).toList();
        TransportVersionDefinition highestDefinition = sortedDefinitions.getFirst();
        TransportVersionId highestId = highestDefinition.ids().getFirst();

View on GitHub (pinned to db6a809a66)

Solutions

1. Open the definition file for the named base ID and renumber patch IDs so they are contiguous from base.0 upward with no gaps.
2. If a gap is intentional during migration, disable density validation temporarily via the task's shouldValidateDensity property and add a TODO, then re-enable after migration (see the existing TODO in validateBase).
3. Regenerate resources with './gradlew generateTransportVersion' after fixing the file to confirm consistency.

Example fix

// before: ids in definition for base 8800000 are [8800000, 8800002]  (8800001 missing)
// after:  renumber to [8800000, 8800001] so patches are dense

// When editing a definition file's ID list, ensure patches within a base are contiguous:
// ids.stream().mapToInt(id -> id.complete()).sorted().toArray() should have adjacent diffs of 1 within the same base.

When it happens

Trigger: A patch ID was deleted from a definition without recompacting; a definition file lists IDs [base.0, base.2] skipping base.1; the density flag (-D...shouldValidateDensity) is on and the sorted-descending IDs within one base show previous.complete()-1 != current.complete().

Common situations: Removing an obsolete transport version from a definition file but leaving its slot; merging two definition files and dropping an intermediate patch; hand-editing ID lists in the resource YAML/CSV.

Related errors

• Transport version definition file [{}] {}
• 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/206cbd67aa2eb15f. Report an issue: GitHub.