What causes "Failed to write unicast_hosts for {}" in elastic/elasticsearch?

Check disk space and write permissions on the test cluster's working directory (often under build/testclusters/).

elastic/elasticsearch · error · UncheckedIOException

Failed to write unicast_hosts for {}

Error message

Failed to write unicast_hosts for {}

What it means

Thrown by ElasticsearchCluster.writeUnicastHostsFiles when Files.writeString fails on any node's configDir/unicast_hosts.txt. unicast_hosts.txt is the discovery seed file the nodes use to find each other; failing to write it breaks cluster formation.

Source

Thrown at build-tools/src/main/java/org/elasticsearch/gradle/testclusters/ElasticsearchCluster.java:551

    }

    @Override
    public void requiresFeature(String feature, Version from) {
        nodes.all(node -> node.requiresFeature(feature, from));
    }

    @Override
    public void requiresFeature(String feature, Version from, Version until) {
        nodes.all(node -> node.requiresFeature(feature, from, until));
    }

    public void writeUnicastHostsFiles() {
        String unicastUris = nodes.stream().flatMap(node -> node.getAllTransportPortURI().stream()).collect(Collectors.joining("\n"));
        nodes.forEach(node -> {
            try {
                Files.writeString(node.getConfigDir().resolve("unicast_hosts.txt"), unicastUris);
            } catch (IOException e) {
                throw new UncheckedIOException("Failed to write unicast_hosts for " + this, e);
            }
        });
    }

    @Override
    @Internal
    public String getHttpSocketURI() {
        waitForAllConditions();
        return getFirstNode().getHttpSocketURI();
    }

    @Override
    @Internal
    public String getTransportPortURI() {
        waitForAllConditions();
        return getFirstNode().getTransportPortURI();
    }

View on GitHub (pinned to db6a809a66)

Solutions

Check disk space and write permissions on the test cluster's working directory (often under build/testclusters/).
Ensure no concurrent process is removing node config dirs while the cluster is being configured.
Clean stale cluster dirs: rm -rf build/testclusters and rerun.
On Windows, verify path lengths stay within OS limits for the cluster home.

Defensive patterns

Strategy: try-catch

Validate before calling

Path dir = node.getConfigDir();
if (!Files.isWritable(dir)) {
    throw new IllegalStateException("Config dir not writable: " + dir);
}
// also check disk: Files.getFileStore(dir).getUsableSpace()

Try / catch

try {
    cluster.writeUnicastHostsFiles();
} catch (UncheckedIOException e) {
    log.error("Failed writing unicast_hosts for {}, cause={}", cluster, e.getCause());
    throw e; // or fall back to retry after ensuring parent dirs exist
}

Prevention

Ensure build/testclusters is on a writable disk with adequate free space.
Avoid concurrent clean tasks that may remove node dirs mid-config.
On Windows, keep cluster home paths short to avoid MAX_PATH limits.

When it happens

Trigger: An IOException while writing the unicast host list for one of the cluster's nodes — disk full, permission denied, parent dir missing, or the node's configDir being invalid.

Common situations: Insufficient disk space in the test working directory; the node's home/config dir was deleted out from under the writer; permission issues in a containerized CI environment; path length limits on Windows.

Related errors

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