testcontainers/testcontainers-java · error · IllegalStateException

Cannot determine Elasticsearch DNS name. When using a…

Error message

Cannot determine Elasticsearch DNS name. When using a custom network, set a network alias on the Elasticsearch container.

What it means

Thrown by resolveExistingEsDnsNameOnNetwork as the last resort when no user-defined network alias and no usable container name can be found for the Elasticsearch container on the shared network. Kibana needs some DNS-resolvable name (alias or container name) to address Elasticsearch and cannot determine one.

Solutions

Set an alias on the Elasticsearch container: elasticsearch.withNetworkAliases("elasticsearch").
Ensure the ES container has a non-empty container name (withCreateContainerCmdModifier cmd -> cmd.withName("elasticsearch")).
Let KibanaContainer create the network itself by removing explicit network configuration from both containers.

Example fix

// before
Network net = Network.newNetwork();
elasticsearch.withNetwork(net); // no alias
kibana.withNetwork(net);
// after
Network net = Network.newNetwork();
elasticsearch.withNetwork(net).withNetworkAliases("elasticsearch");
kibana.withNetwork(net);

Defensive patterns

Strategy: fallback

Validate before calling

elasticsearch.withNetwork(net).withNetworkAliases("elasticsearch"); // alias guarantees DNS name

Type guard

boolean hasDnsName(ElasticsearchContainer es) { return es.getNetworkAliases().stream().anyMatch(a -> !a.startsWith("tc-")) || es.getContainerName() != null; }

Try / catch

try { kibana.start(); } catch (IllegalStateException e) { if (e.getMessage().contains("Cannot determine Elasticsearch DNS name")) throw new ConfigException("Set withNetworkAliases(\"elasticsearch\") on the ES container"); throw e; }

Prevention

Always set withNetworkAliases on the Elasticsearch container when using a custom network
Avoid container naming schemes that produce empty names
Let KibanaContainer manage the network if you don't need custom DNS

When it happens

Trigger: Managed mode on a custom network where the ES container has no network alias set via withNetworkAliases(...) and its container name is null/blank.

Common situations: Using a manually created Network without aliases; stripping container names with a naming strategy that yields empty names; upgrading Testcontainers where default aliases were no longer auto-applied.

Understand the failure class

Background: 'Could not be found', 'does not exist', 'not found in database': the resource-not-found family when an ID, slug, key, or URI lookup comes back empty — this error's family across 20 libraries.

Related errors

AI-assisted analysis of testcontainers/testcontainers-java@8e549514e3 (2026-09-12). Data as JSON: /api/errors/38550df0c0ba0dd6. Report an issue: GitHub.

Appendix: source

Thrown at modules/elasticsearch/src/main/java/org/testcontainers/elasticsearch/KibanaContainer.java:459

                    String cleaned = alias.trim();
                    // Skip Testcontainers auto-generated aliases (tc-*), prefer user-defined ones
                    if (!cleaned.startsWith("tc-")) {
                        log.info("Using Elasticsearch network alias: {}", cleaned);
                        return cleaned;
                    }
                }
            }
        }

        // Fallback: use container name
        String containerName = info.getName();
        if (containerName != null && !containerName.trim().isEmpty()) {
            String dnsName = containerName.replaceFirst("^/", "").trim();
            log.info("No user-defined network alias found, using Elasticsearch container name: {}", dnsName);
            return dnsName;
        }

        throw new IllegalStateException(
            "Cannot determine Elasticsearch DNS name. " +
            "When using a custom network, set a network alias on the Elasticsearch container."
        );
    }

    private ContainerNetwork findNetworkEndpoint(Map<String, ContainerNetwork> networks, Network network) {
        // Try network ID first
        ContainerNetwork endpoint = networks.get(network.getId());
        if (endpoint != null) {
            return endpoint;
        }

        // Try network name as fallback (Docker may key by name instead of ID)
        try {
            String networkName = DockerClientFactory
                .instance()
                .client()
                .inspectNetworkCmd()

View on GitHub (pinned to 8e549514e3)