What causes "Could not control proxy" in testcontainers/testcontainers-java?

Check toxiproxy container is running and reachable before toggling cut state

testcontainers/testcontainers-java · error · RuntimeException

Could not control proxy

Error message

Could not control proxy

What it means

ToxiProxyContainer.setConnectionCut() toggles connection-cutting toxics on the proxy via the toxiproxy HTTP client. Any IOException while adding/removing the toxic wrappers is wrapped in a RuntimeException with the message 'Could not control proxy', so the test fails loudly rather than silently leaving proxy state ambiguous.

Solutions

Check toxiproxy container is running and reachable before toggling cut state
Ensure the proxy is still registered (proxy name unchanged) and its toxics CUT_CONNECTION_DOWNSTREAM/UPSTREAM exist
Catch the RuntimeException and retry after re-establishing the proxy if the test tolerates transient control-plane failures
Verify Docker network connectivity and that the toxiproxy port mapping is exposed

Example fix

// before
container.getProxy(x).setConnectionCut(true);
// after
if (container.isRunning()) {
    container.getProxy(x).setConnectionCut(true);
}

Defensive patterns

Strategy: retry

Validate before calling

if (!toxiproxyContainer.isRunning()) throw new IllegalStateException("toxiproxy container not running");

Try / catch

try { proxy.setConnectionCut(true); } catch (RuntimeException e) { /* retry once after brief sleep; toxiproxy control-plane hiccup */ }

Prevention

Verify toxiproxy container health before toggling cut state
Keep proxy registration names stable across test phases
Avoid stopping the toxiproxy container while proxies are mid-toggle

When it happens

Trigger: Calling setConnectionCut(true/false) when the toxiproxy server has dropped, the container's proxy was removed/recreated, or the underlying proxy API connection fails with an IOException.

Common situations: Tests that cut connections under load; toxiproxy container being stopped concurrently; proxy registered under a name that no longer exists on the toxiproxy server; Docker network hiccups between test and toxiproxy container.

Understand the failure class

Background: 'Something went wrong' / 'Request failed (500)' / 'HTTP error! status: 404' — what failed HTTP requests actually mean and how to find the real cause — this error's family across 28 libraries.

Related errors

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

Appendix: source

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

        }

        /**
         * Cuts the connection by setting bandwidth in both directions to zero.
         * @param shouldCutConnection true if the connection should be cut, or false if it should be re-enabled
         */
        public void setConnectionCut(boolean shouldCutConnection) {
            try {
                if (shouldCutConnection) {
                    toxics().bandwidth(CUT_CONNECTION_DOWNSTREAM, ToxicDirection.DOWNSTREAM, 0);
                    toxics().bandwidth(CUT_CONNECTION_UPSTREAM, ToxicDirection.UPSTREAM, 0);
                    isCurrentlyCut = true;
                } else if (isCurrentlyCut) {
                    toxics().get(CUT_CONNECTION_DOWNSTREAM).remove();
                    toxics().get(CUT_CONNECTION_UPSTREAM).remove();
                    isCurrentlyCut = false;
                }
            } catch (IOException e) {
                throw new RuntimeException("Could not control proxy", e);
            }
        }
    }
}

View on GitHub (pinned to 8e549514e3)