elastic/elasticsearch · error · UncheckedIOException

Failed to read transport ports file: {} for {}

Error message

Failed to read transport ports file: {} for {}

What it means

Thrown by getTransportPortInternal() when readPortsFile(transportPortFile) throws IOException. The transport ports file is written by ES on startup; this method reads it back to discover which port the node bound to. Failure means the file is missing, unreadable, or malformed.

Source

Thrown at build-tools/src/main/java/org/elasticsearch/gradle/testclusters/ElasticsearchNode.java:1559

            // temporarily check the old substitution first so both old and new work during backport
            errorFileSub = new ReplacementKey("-XX:ErrorFile=logs/hs_err_pid%p.log", "-XX:ErrorFile=hs_err_pid%p.log");
        }
        expansions.put(errorFileSub, "-XX:ErrorFile=" + confPathLogs.resolve("hs_err_pid%p.log"));

        return expansions;
    }

    private void checkFrozen() {
        if (configurationFrozen.get()) {
            throw new IllegalStateException("Configuration for " + this + " can not be altered, already locked");
        }
    }

    private List<String> getTransportPortInternal() {
        try {
            return readPortsFile(transportPortFile);
        } catch (IOException e) {
            throw new UncheckedIOException("Failed to read transport ports file: " + transportPortFile + " for " + this, e);
        }
    }

    private List<String> getHttpPortInternal() {
        try {
            return readPortsFile(httpPortsFile);
        } catch (IOException e) {
            throw new UncheckedIOException("Failed to read http ports file: " + httpPortsFile + " for " + this, e);
        }
    }

    private List<String> getReadinessPortInternal() {
        try {
            return readPortsFile(readinessPortsFile);
        } catch (IOException e) {
            return new ArrayList<>();
        }
    }

View on GitHub (pinned to db6a809a66)

Solutions

1. Confirm the node actually started (check esOutputFile for the 'started' line and any startup exception).
2. Wait for node readiness via the built-in wait logic before querying ports.
3. Ensure no parallel teardown is deleting the working dir while ports are being read.
4. Re-run the test in isolation to rule out cross-cluster file races.

if (Files.notExists(transportPortFile)) {
    return List.of();  // or wait for readiness first
}

try {
    return readPortsFile(transportPortFile);
} catch (IOException e) {
    throw new UncheckedIOException("Failed to read transport ports file: " + transportPortFile + " for " + this, e);
}

When it happens

Trigger: Called during getTransportPort()/getTransportSocketURI() before ES has finished writing the ports file, after the file was deleted, or when the node never started successfully enough to bind the transport port.

Common situations: Polling the node's transport port too early in the startup wait loop; the node crashed before writing transport ports; a previous run's ports file was not cleaned up and is stale/unreadable; concurrency where teardown deleted the file mid-read.

Related errors

• Failed to read http ports file: {} for {}
• Failed to write unicast_hosts for {}
• IO error while waiting cluster
• Failed to create working directory for {}, with: {}
• Can't create extra config file for

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