testcontainers/testcontainers-java · error · IllegalStateException

Elasticsearch container has no network configuration

Error message

Elasticsearch container has no network configuration

What it means

Thrown by resolveExistingEsDnsNameOnNetwork when Docker's inspect of the Elasticsearch container reports null network settings — i.e. no network configuration is retrievable. KibanaContainer resolves Elasticsearch's DNS name on the shared network via this lookup, so it cannot proceed.

Solutions

  1. Start the ElasticsearchContainer and wait for it to be ready before KibanaContainer resolves its DNS name (start Kibana after ES, or in the same managed setup).
  2. Verify the ES container is actually running: docker inspect <esId> and check NetworkSettings.Networks.
  3. Recreate the containers if the ID is stale from a previous run.

Example fix

// before
KibanaContainer kibana = new KibanaContainer(elasticsearch);
kibana.start(); // elasticsearch never started
// after
elasticsearch.start();
KibanaContainer kibana = new KibanaContainer(elasticsearch);
kibana.start();
Defensive patterns

Strategy: retry

Validate before calling

InspectContainerResponse info = DockerClientFactory.instance().client().inspectContainerCmd(elasticsearch.getContainerId()).exec();
if (info.getNetworkSettings().getNetworks() == null) throw new IllegalStateException("ES container has no networks; ensure it is started");

Try / catch

try { kibana.start(); } catch (IllegalStateException e) { if (e.getMessage().contains("has no network configuration")) { elasticsearch.start(); kibana.start(); } else throw e; }

Prevention

When it happens

Trigger: Calling hosts()/start() on a managed setup while Docker inspect of the Elasticsearch container ID returns networks == null — typically a race where the container isn't fully started, or the container ID is stale/invalid.

Common situations: Resolving the ES hostname before elasticsearch.start() finished; Docker daemon anomalies or heavily customized network modes (e.g. none/host interactions).

Related errors

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

Appendix: source

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

        // Managed-mode safety rule: by the time Kibana is configuring itself, Elasticsearch must already be
        // started (via dependsOn)
        String esId = requireElasticsearchContainerId();

        // Elasticsearch is already created/started. Attach it to the ad-hoc network.
        // We don't need to provide an explicit alias - we'll use the container name for DNS resolution.
        // Equivalent of https://docs.docker.com/reference/cli/docker/network/connect/
        connectRunningContainerToNetwork(esId, createdSharedNetwork);
    }

    private String resolveExistingEsDnsNameOnNetwork(Network network) {
        String esId = requireElasticsearchContainerId();

        InspectContainerResponse info = DockerClientFactory.instance().client().inspectContainerCmd(esId).exec();

        Map<String, ContainerNetwork> networks = info.getNetworkSettings().getNetworks();
        if (networks == null) {
            throw new IllegalStateException("Elasticsearch container has no network configuration");
        }

        // Try to find the network endpoint - Docker may key by network name or ID
        ContainerNetwork endpoint = findNetworkEndpoint(networks, network);
        if (endpoint == null) {
            throw new IllegalStateException(
                "Elasticsearch container is not connected to the expected network. " +
                "Ensure both containers use the same Network instance."
            );
        }

        // Prefer user-defined network aliases (skip Testcontainers auto-generated tc-* aliases)
        if (endpoint.getAliases() != null && !endpoint.getAliases().isEmpty()) {
            for (String alias : endpoint.getAliases()) {
                if (StringUtils.isNotBlank(alias)) {
                    String cleaned = alias.trim();
                    // Skip Testcontainers auto-generated aliases (tc-*), prefer user-defined ones
                    if (!cleaned.startsWith("tc-")) {

View on GitHub (pinned to 8e549514e3)