testcontainers/testcontainers-java · error · IllegalStateException

Failed to connect Elasticsearch container to ad-hoc shared…

Error message

Failed to connect Elasticsearch container to ad-hoc shared network

What it means

When Kibana runs in managed mode against a pre-existing Elasticsearch network setup, the library creates an ad-hoc shared Docker network and connects the already-running Elasticsearch container to it via connectToNetworkCmd(). If the Docker API call throws for any reason, the library wraps it in this IllegalStateException to signal the shared-network setup failed.

Solutions

1. Retry the test setup; transient Docker daemon failures are the usual cause.
2. Check Docker daemon health (docker ps, docker network ls) and that the ES container is still running when Kibana starts.
3. Avoid parallel test suites sharing ad-hoc networks; give each test its own network/container chain.
4. Ensure Docker and testcontainers versions are current — older docker-java versions have network-connect race bugs.

// wrap test startup
try {
    kibana.start();
} catch (IllegalStateException e) {
    if (e.getMessage() != null && e.getMessage().contains("ad-hoc shared network")) {
        // transient docker failure: verify daemon, then retry once
        if (!dockerDaemonHealthy()) throw e;
        es.stop(); kibana.stop(); retrySetup();
    } else throw e;
}

When it happens

Trigger: Docker daemon rejecting connectToNetworkCmd for the running ES container: network already removed mid-test, container stopped between network creation and connect, Docker daemon restart, or any exception from the docker-java client during the exec() call.

Common situations: Flaky CI environments where the Docker daemon is restarted or under load; running tests with remote/docker-in-docker setups where network operations behave differently; parallel tests tearing down shared networks while another test connects a container.

Related errors

• Elasticsearch container has no network configuration
• Elasticsearch container is not connected to the expected…
• withReuse(true) is not supported for KibanaContainer in…
• Cannot set Elasticsearch URL when using Elasticsearch…
• Failed to copy Elasticsearch HTTP CA certificate from

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

Appendix: source

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

                "before KibanaContainer is started."
            );
        }
        return id.trim();
    }

    private void connectRunningContainerToNetwork(String containerId, Network network) {
        String networkId = network.getId();

        try {
            DockerClientFactory
                .instance()
                .client()
                .connectToNetworkCmd()
                .withContainerId(containerId)
                .withNetworkId(networkId)
                .exec();
        } catch (Exception e) {
            throw new IllegalStateException("Failed to connect Elasticsearch container to ad-hoc shared network", e);
        }
    }

    private static void ensureCompatibleVersion(String esVersion) {
        ComparableVersion comparableVersion = new ComparableVersion(esVersion);
        if (comparableVersion.isLessThan(MINIMUM_SUPPORTED_VERSION)) {
            throw new IllegalArgumentException(
                String.format(
                    "Kibana version %s is not supported. Minimum version is %s",
                    comparableVersion,
                    MINIMUM_SUPPORTED_VERSION
                )
            );
        }
    }

    private String createKibanaServiceAccountToken(String protocol) {
        if (elasticsearch == null) {

View on GitHub (pinned to 8e549514e3)