What causes "Failed to read http ports file: {} for {}" in elastic/elasticsearch?

Use the cluster's built-in waitForHttp / readiness mechanism rather than reading ports manually.

elastic/elasticsearch · error · UncheckedIOException

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

Error message

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

What it means

Sibling of error 93: thrown by getHttpPortInternal() when readPortsFile(httpPortsFile) throws IOException. Same lifecycle — the http ports file is written by ES on startup and read back to discover the bound HTTP port for REST clients.

Source

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

    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<>();
        }
    }

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

View on GitHub (pinned to db6a809a66)

Solutions

Use the cluster's built-in waitForHttp / readiness mechanism rather than reading ports manually.
Check esOutputFile to confirm ES bound the HTTP port (look for 'publish_address' under http).
Ensure the working dir is not being concurrently cleaned.
Re-run in isolation if cross-test interference is suspected.

Defensive patterns

Strategy: try-catch

Validate before calling

if (Files.notExists(httpPortsFile)) {
    return List.of();
}

Try / catch

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

Prevention

Use the cluster's waitForHttp readiness gate rather than reading ports manually.
Confirm ES bound the HTTP port via the log file before reading.
Do not let teardown race with port reads.

When it happens

Trigger: getHttpPort()/getHttpSocketURI() is called before ES wrote the http ports file, or the file is missing/unreadable. Note: getReadinessPortInternal() swallows IOException and returns empty list — only http and transport throw.

Common situations: Calling getHttpPort() during a too-early readiness probe; node crashed before binding HTTP; the ports file was deleted by a concurrent cleanup; permissions issue on the ports file.

Related errors

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