testcontainers/testcontainers-java · warning

Container needs to be on more than one custom network to…

Error message

Container needs to be on more than one custom network to link to other containers - this is not currently supported. Required networks are: {}

What it means

In applyConfiguration, when a container is linked (withLinks) to other containers residing on multiple distinct custom networks, Testcontainers cannot represent that legacy-links topology and warns. Links are a legacy Docker feature; the container will not be attached to all requested networks, which can break inter-container DNS resolution.

Solutions

Replace withLinks with a shared Network: create Network.newNetwork() and attach all containers via withNetwork(network)
Keep all linked containers on a single custom network so the condition does not trigger
Use network aliases and container names for DNS-based discovery instead of legacy links

Example fix

// before
appContainer.withLinks(dbContainer, cacheContainer); // db and cache on different custom networks
// after
Network network = Network.newNetwork();
dbContainer.withNetwork(network).withNetworkAliases("db");
cacheContainer.withNetwork(network).withNetworkAliases("cache");
appContainer.withNetwork(network);

Defensive patterns

Strategy: validation

Validate before calling

// Ensure all interdependent containers share exactly one custom network
Network net = Network.newNetwork();
Preconditions.checkState(
    db.getNetwork() == net && cache.getNetwork() == net,
    "All linked containers must be on the same custom network"
);
app.withNetwork(net);

Prevention

Prefer shared Network + network aliases over legacy withLinks
Attach all interdependent containers to a single custom network
Remove 'bridge' from any network bookkeeping — it is excluded from the check

When it happens

Trigger: Container has withLinks(...) to containers that live on more than one non-bridge custom network — the resulting allLinkedContainerNetworks set (minus 'bridge') has size > 1.

Common situations: Migrating legacy link-based topologies to network-based ones; mixing containers started on separate custom networks and linking them together instead of using shared networks.

Related errors

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

Appendix: source

Thrown at core/src/main/java/org/testcontainers/containers/GenericContainer.java:810

            if (allLinks.size() == 0) {
                throw new ContainerLaunchException(
                    "Aborting attempt to link to container " +
                    linkableContainer.getContainerName() +
                    " as it is not running"
                );
            }

            Set<String> linkedContainerNetworks = findAllNetworksForLinkedContainers(linkableContainer);
            allLinkedContainerNetworks.addAll(linkedContainerNetworks);
        }

        createCommand.withLinks(allLinks.toArray(new Link[allLinks.size()]));

        allLinkedContainerNetworks.remove("bridge");
        if (allLinkedContainerNetworks.size() > 1) {
            logger()
                .warn(
                    "Container needs to be on more than one custom network to link to other " +
                    "containers - this is not currently supported. Required networks are: {}",
                    allLinkedContainerNetworks
                );
        }

        Optional<String> networkForLinks = allLinkedContainerNetworks.stream().findFirst();
        if (networkForLinks.isPresent()) {
            logger().debug("Associating container with network: {}", networkForLinks.get());
            createCommand.withNetworkMode(networkForLinks.get());
        }

        if (hostAccessible) {
            PortForwardingContainer.INSTANCE.start();
        }
        PortForwardingContainer.INSTANCE
            .getNetwork()
            .ifPresent(it -> {

View on GitHub (pinned to 8e549514e3)