{"record":{"id":"e01fe8a7d9538d09","repo":"testcontainers/testcontainers-java","slug":"container-needs-to-be-on-more-than-one-custom-network-to","errorCode":null,"errorMessage":"Container needs to be on more than one custom network to link to other containers - this is not currently supported. Required networks are: {}","messagePattern":"Container needs to be on more than one custom network to link to other containers - this is not currently supported\\. Required networks are: (.+?)","errorType":"console","errorClass":null,"httpStatus":null,"severity":"warning","filePath":"core/src/main/java/org/testcontainers/containers/GenericContainer.java","lineNumber":810,"sourceCode":"\n            if (allLinks.size() == 0) {\n                throw new ContainerLaunchException(\n                    \"Aborting attempt to link to container \" +\n                    linkableContainer.getContainerName() +\n                    \" as it is not running\"\n                );\n            }\n\n            Set<String> linkedContainerNetworks = findAllNetworksForLinkedContainers(linkableContainer);\n            allLinkedContainerNetworks.addAll(linkedContainerNetworks);\n        }\n\n        createCommand.withLinks(allLinks.toArray(new Link[allLinks.size()]));\n\n        allLinkedContainerNetworks.remove(\"bridge\");\n        if (allLinkedContainerNetworks.size() > 1) {\n            logger()\n                .warn(\n                    \"Container needs to be on more than one custom network to link to other \" +\n                    \"containers - this is not currently supported. Required networks are: {}\",\n                    allLinkedContainerNetworks\n                );\n        }\n\n        Optional<String> networkForLinks = allLinkedContainerNetworks.stream().findFirst();\n        if (networkForLinks.isPresent()) {\n            logger().debug(\"Associating container with network: {}\", networkForLinks.get());\n            createCommand.withNetworkMode(networkForLinks.get());\n        }\n\n        if (hostAccessible) {\n            PortForwardingContainer.INSTANCE.start();\n        }\n        PortForwardingContainer.INSTANCE\n            .getNetwork()\n            .ifPresent(it -> {","sourceCodeStart":792,"sourceCodeEnd":828,"githubUrl":"https://github.com/testcontainers/testcontainers-java/blob/8e549514e3f01c57d70546fbb8599d138f3903e5/core/src/main/java/org/testcontainers/containers/GenericContainer.java#L792-L828","documentation":"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.","triggerScenarios":"Container has withLinks(...) to containers that live on more than one non-bridge custom network — the resulting allLinkedContainerNetworks set (minus 'bridge') has size > 1.","commonSituations":"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.","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"],"exampleFix":"// before\nappContainer.withLinks(dbContainer, cacheContainer); // db and cache on different custom networks\n// after\nNetwork network = Network.newNetwork();\ndbContainer.withNetwork(network).withNetworkAliases(\"db\");\ncacheContainer.withNetwork(network).withNetworkAliases(\"cache\");\nappContainer.withNetwork(network);","handlingStrategy":"validation","validationCode":"// Ensure all interdependent containers share exactly one custom network\nNetwork net = Network.newNetwork();\nPreconditions.checkState(\n    db.getNetwork() == net && cache.getNetwork() == net,\n    \"All linked containers must be on the same custom network\"\n);\napp.withNetwork(net);","typeGuard":null,"tryCatchPattern":null,"preventionTips":["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"],"tags":["networking","container-links","topology","non-fatal"],"backgroundTag":"multiple-networks-unsupported","analyzedSha":"8e549514e3f01c57d70546fbb8599d138f3903e5","analyzedAt":"2026-09-12T14:56:41.227Z","contentChangedAt":"2026-09-12T14:56:41.227Z","schemaVersion":2},"datasetVersion":"2026-09-16T04:17:20.429Z"}