{"record":{"id":"0a81f49811294c5d","repo":"testcontainers/testcontainers-java","slug":"maximum-number-of-proxies-exceeded","errorCode":null,"errorMessage":"Maximum number of proxies exceeded","messagePattern":"Maximum number of proxies exceeded","errorType":"exception","errorClass":"IllegalStateException","httpStatus":null,"severity":"error","filePath":"modules/toxiproxy/src/main/java/org/testcontainers/containers/ToxiproxyContainer.java","lineNumber":130,"sourceCode":"     * useful in most scenarios, but this method is present to allow use of Toxiproxy in front of containers\n     * or external servers that are not managed by Testcontainers.</em></p>\n     *\n     * @param hostname hostname of target server to be proxied\n     * @param port port number on the target server that should be proxied\n     * @return a {@link ContainerProxy} instance\n     * @deprecated {@link ToxiproxyContainer} will not build the client. Proxies should be provided manually.\n     */\n    @Deprecated\n    public ContainerProxy getProxy(String hostname, int port) {\n        String upstream = hostname + \":\" + port;\n\n        return proxies.computeIfAbsent(\n            upstream,\n            __ -> {\n                try {\n                    final int toxiPort = nextPort.getAndIncrement();\n                    if (toxiPort > LAST_PROXIED_PORT) {\n                        throw new IllegalStateException(\"Maximum number of proxies exceeded\");\n                    }\n\n                    final Proxy proxy = client.createProxy(upstream, \"0.0.0.0:\" + toxiPort, upstream);\n                    final int mappedPort = getMappedPort(toxiPort);\n                    return new ContainerProxy(proxy, getHost(), mappedPort, toxiPort);\n                } catch (IOException e) {\n                    throw new RuntimeException(\"Proxy could not be created\", e);\n                }\n            }\n        );\n    }\n\n    @RequiredArgsConstructor(access = AccessLevel.PROTECTED)\n    @Deprecated\n    public static class ContainerProxy {\n\n        private static final String CUT_CONNECTION_DOWNSTREAM = \"CUT_CONNECTION_DOWNSTREAM\";\n","sourceCodeStart":112,"sourceCodeEnd":148,"githubUrl":"https://github.com/testcontainers/testcontainers-java/blob/8e549514e3f01c57d70546fbb8599d138f3903e5/modules/toxiproxy/src/main/java/org/testcontainers/containers/ToxiproxyContainer.java#L112-L148","documentation":"ToxiproxyContainer allocates one container port per proxy from a fixed range (nextPort counter up to LAST_PROXIED_PORT). When more distinct upstreams are requested than ports in the range, getProxy throws this IllegalStateException.","triggerScenarios":"Calling getProxy(new HostAndPort(...)) for more unique upstreams than the pre-allocated port range allows (containers created without extra exposed ports / with fewer than needed proxy slots).","commonSituations":"Large test topologies proxying many backing services through one Toxiproxy container; creating multiple proxies for the same test class without reusing the container's proxy slots.","solutions":["Reduce the number of distinct upstreams proxied through the single Toxiproxy container.","Create additional ToxiproxyContainer instances and distribute upstreams among them.","Reuse one ContainerProxy per upstream (getProxy already caches by upstream) instead of expecting unlimited slots.","Build the container with a larger port range if supported by your testcontainers version, or bump to a version with a wider default range."],"exampleFix":"// before\nfor (HostAndPort upstream : fiftyUpstreams) {\n    container.getProxy(upstream); // exhausts port range\n}\n// after\n// spread across two containers\nToxiproxyContainer c1 = new ToxiproxyContainer(\"ghcr.io/shopify/toxiproxy:2.11.0\");\nToxiproxyContainer c2 = new ToxiproxyContainer(\"ghcr.io/shopify/toxiproxy:2.11.0\");\nfor (int i = 0; i < fiftyUpstreams.size(); i++) {\n    (i < 25 ? c1 : c2).getProxy(fiftyUpstreams.get(i));\n}","handlingStrategy":"fallback","validationCode":"if (distinctUpstreams.size() > 20) {\n    throw new IllegalArgumentException(\"too many upstreams for one ToxiproxyContainer; split across containers\");\n}","typeGuard":null,"tryCatchPattern":"try { proxy = toxiproxy.getProxy(upstream); } catch (IllegalStateException e) { if (e.getMessage().contains(\"Maximum number of proxies exceeded\")) { toxiproxy2.start(); proxy = toxiproxy2.getProxy(upstream); } else throw e; }","preventionTips":["Count distinct upstreams before provisioning and provision enough Toxiproxy containers.","Rely on getProxy's per-upstream caching instead of creating new containers per proxy."],"tags":["toxiproxy","testcontainers","resource-exhaustion"],"backgroundTag":"value-out-of-range","analyzedSha":"8e549514e3f01c57d70546fbb8599d138f3903e5","analyzedAt":"2026-09-12T14:56:41.227Z","contentChangedAt":"2026-09-12T14:56:41.227Z","schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}