testcontainers/testcontainers-java · error · RuntimeException

Proxy could not be created

Error message

Proxy could not be created

What it means

ToxiproxyContainer.getProxy delegates proxy creation to the Toxiproxy HTTP client (client.createProxy). Any IOException from that API call is wrapped in this RuntimeException with the original exception as the cause.

Solutions

1. Read the cause (getCause) — it contains the real IOException from the Toxiproxy API.
2. Ensure the container is started before calling getProxy.
3. Verify the upstream HostAndPort is reachable and correctly formatted.
4. Check container logs for Toxiproxy server errors and restart the container if the server died.

Example fix

// before
ToxiproxyContainer container = new ToxiproxyContainer("ghcr.io/shopify/toxiproxy:2.11.0");
container.getProxy(HostAndPort.fromString("db:5432")); // not started
// after
ToxiproxyContainer container = new ToxiproxyContainer("ghcr.io/shopify/toxiproxy:2.11.0");
container.start();
container.getProxy(HostAndPort.fromString("db:5432"));

if (!container.isRunning()) throw new IllegalStateException("start the ToxiproxyContainer before calling getProxy");

try { proxy = toxiproxy.getProxy(upstream); } catch (RuntimeException e) { if (e.getMessage().equals("Proxy could not be created")) { throw new IllegalStateException("toxiproxy API call failed", e.getCause()); } throw e; }

When it happens

Trigger: client.createProxy(upstream, "0.0.0.0:<port>", upstream) throws IOException — Toxiproxy's HTTP API is unreachable, the port is already in use inside the container, or the upstream address is malformed/rejected.

Common situations: Calling getProxy before container.start(), port mapping conflicts, Toxiproxy server crashed inside the container, or invalid upstream host/port syntax.

Understand the failure class

Background: "API request failed": what wrapped HTTP errors from external APIs mean and how to find the real cause — this error's family across 29 libraries.

Related errors

• Cannot determine Elasticsearch DNS name. When using a…
• Could not control proxy
• DOCKER_HOST is not listening
• Elasticsearch and Kibana have different networks…
• Elasticsearch container has no network configuration

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

Appendix: source

Thrown at modules/toxiproxy/src/main/java/org/testcontainers/containers/ToxiproxyContainer.java:137

     */
    @Deprecated
    public ContainerProxy getProxy(String hostname, int port) {
        String upstream = hostname + ":" + port;

        return proxies.computeIfAbsent(
            upstream,
            __ -> {
                try {
                    final int toxiPort = nextPort.getAndIncrement();
                    if (toxiPort > LAST_PROXIED_PORT) {
                        throw new IllegalStateException("Maximum number of proxies exceeded");
                    }

                    final Proxy proxy = client.createProxy(upstream, "0.0.0.0:" + toxiPort, upstream);
                    final int mappedPort = getMappedPort(toxiPort);
                    return new ContainerProxy(proxy, getHost(), mappedPort, toxiPort);
                } catch (IOException e) {
                    throw new RuntimeException("Proxy could not be created", e);
                }
            }
        );
    }

    @RequiredArgsConstructor(access = AccessLevel.PROTECTED)
    @Deprecated
    public static class ContainerProxy {

        private static final String CUT_CONNECTION_DOWNSTREAM = "CUT_CONNECTION_DOWNSTREAM";

        private static final String CUT_CONNECTION_UPSTREAM = "CUT_CONNECTION_UPSTREAM";

        private final Proxy toxi;

        /**
         * The IP address that this proxy container may be reached on from the host machine.
         */

View on GitHub (pinned to 8e549514e3)