elastic/elasticsearch · error · IllegalStateException

Invalid transport version upper bound file [{}]: {}

Error message

Invalid transport version upper bound file [{}]: {}

What it means

IllegalStateException from TransportVersionUpperBound.fromString() when the first non-comment line of an upper-bound CSV does not split into exactly 2 comma-separated fields (definitionName, versionId). Comment lines starting with '#' are skipped, then the next line must have the shape '<name>,<id>'.

Source

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

        String filename = file.getFileName().toString();
        assert filename.endsWith(".csv");
        int slashIndex = filename.lastIndexOf('/');
        String branch = filename.substring(slashIndex == -1 ? 0 : (slashIndex + 1), filename.length() - 4);

        String idsLine = null;
        // Regardless of whether windows newlines exist (they could be added by git), we split on line feed.
        // All we care about skipping lines with the comment character, so the remaining \r won't matter
        String[] lines = contents.split("\n");
        for (String line : lines) {
            line = line.strip();
            if (line.startsWith("#") == false) {
                idsLine = line;
                break;
            }
        }
        String[] parts = idsLine.split(",");
        if (parts.length != 2) {
            throw new IllegalStateException("Invalid transport version upper bound file [" + file + "]: " + contents);
        }

        return new TransportVersionUpperBound(branch, parts[0], TransportVersionId.fromString(parts[1]));
    }
}

View on GitHub (pinned to db6a809a66)

Solutions

1. Open the upper-bound file named in the message and verify its first non-comment line is exactly 'definitionName,versionId'.
2. Remove stray columns/commas; ensure the version id is present.
3. Restore the file from git history if unsure of the intended contents.

Example fix

// before: 9.x.csv contains "initial_25"
// after:  9.x.csv contains "initial_25,1000000"

String[] parts = idsLine.split(",");
if (parts.length != 2 || parts[0].isBlank() || !parts[1].matches("\\d+")) {
    throw new IllegalStateException("Upper bound file must be 'definitionName,versionId': " + contents);
}

static boolean isValidUpperBoundLine(String line) {
    String[] p = line.split(",");
    return p.length == 2 && !p[0].isBlank() && p[1].matches("\\d+");
}

When it happens

Trigger: An upper-bound CSV's content line has zero, one, or more than one comma - blank content, a single token, or a line with extra fields all trigger this.

Common situations: Hand-editing an upper-bound file and omitting the id or adding extra columns; a merge conflict marker left on the content line; trailing comma producing an empty third part; file accidentally emptied.

Related errors

• Failed to parse id {} in {}
• Invalid transport version data file [{}]: {}
• Could not find base id: {}
• Could not find base id: {}
• Invalid increment {}, must be a positive integer

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