testcontainers/testcontainers-java · error · IllegalStateException

Managed mode requires either both containers share the same…

Error message

Managed mode requires either both containers share the same explicit network, or neither specifies a network (KibanaContainer will create one).

What it means

Thrown by ensureCorrectNetworkSetupForManagedMode when exactly one of the Elasticsearch container and the KibanaContainer has an explicit Docker network configured (XOR condition (esNetwork == null) != (kbNetwork == null)). In managed mode the two must be on the same network so Kibana can reach Elasticsearch by DNS name.

Solutions

Apply the same Network instance to both containers (elasticsearch.withNetwork(network) and kibana.withNetwork(network)).
Or remove withNetwork from both and let KibanaContainer create a shared network automatically.
Ensure withCreateContainerCmdModifier-based network hacks aren't applied to only one side.

Example fix

// before
Network net = Network.newNetwork();
kibana.withNetwork(net); // only Kibana has a network
// after
Network net = Network.newNetwork();
elasticsearch.withNetwork(net);
kibana.withNetwork(net);

Defensive patterns

Strategy: validation

Validate before calling

Network net = Network.newNetwork();
elasticsearch.withNetwork(net);
kibana.withNetwork(net); // XOR check: both or neither

Type guard

boolean networksConsistent(GenericContainer<?> es, GenericContainer<?> kb) { return (es.getNetwork() == null) == (kb.getNetwork() == null); }

Try / catch

try { kibana.start(); } catch (IllegalStateException e) { if (e.getMessage().contains("Managed mode requires")) throw new ConfigException("Apply withNetwork to both or neither container"); throw e; }

Prevention

Create one Network instance and share it between both containers
Or skip withNetwork entirely and let KibanaContainer create a network
Never configure networks on only one container of a managed pair

When it happens

Trigger: Calling kibana.withNetwork(myNetwork) while the ElasticsearchContainer has no network (or vice versa) before starting KibanaContainer in managed (constructor-injected) mode.

Common situations: Adding a custom network only to the Kibana container for other tooling; copy-pasting a network setup example onto just one of the two containers.

Understand the failure class

Background: Conflicting config options: "cannot be used together" — configuration validation errors across open-source libraries — this error's family across 162 libraries.

Related errors

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

Appendix: source

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

        try {
            return elasticsearch.copyFileFromContainer(elasticsearch.getCertPath(), IOUtils::toByteArray);
        } catch (Exception e) {
            throw new IllegalStateException(
                "Failed to copy Elasticsearch HTTP CA certificate from '" +
                elasticsearch.getCertPath() +
                "'. " +
                "In managed HTTPS mode, KibanaContainer requires access to the Elasticsearch HTTP CA.",
                e
            );
        }
    }

    private void ensureCorrectNetworkSetupForManagedMode() {
        Network esNetwork = elasticsearch.getNetwork();
        Network kbNetwork = this.getNetwork();

        if ((esNetwork == null) != (kbNetwork == null)) {
            throw new IllegalStateException(
                "Managed mode requires either both containers share the same explicit network, " +
                "or neither specifies a network (KibanaContainer will create one). "
            );
        }

        // Both explicit: must be same
        if (esNetwork != kbNetwork) {
            throw new IllegalStateException(
                "Elasticsearch and Kibana have different networks configured. " +
                "In managed mode both containers must share the same explicit network instance, " +
                "or neither must define a network."
            );
        }
    }

    private void createAdHocNetwork() {
        // Fully managed: create ad-hoc network and own it.
        createdSharedNetwork = Network.newNetwork();

View on GitHub (pinned to 8e549514e3)