testcontainers/testcontainers-java · error · IllegalStateException

Could not obtain SSH_CONNECTION environment variable for…

Error message

Could not obtain SSH_CONNECTION environment variable for docker machine ${defaultMachine}

What it means

Thrown by GenericContainer.getTestHostIpAddress() when TestContainers is running against a docker-machine VM and the command `docker-machine ssh <machine> echo $SSH_CONNECTION` returns an empty string. The library needs the SSH connection details to derive the VM's IP address, and without SSH_CONNECTION it cannot determine the docker host the test container is reachable on. It wraps the failure in an IllegalStateException because it indicates an unexpectedly broken docker-machine environment.

Solutions

Verify the docker-machine VM is running and healthy: `docker-machine ls` then `docker-machine start <machine>` and `docker-machine env <machine>`.
Run `docker-machine ssh <machine> echo $SSH_CONNECTION` manually; if empty, regenerate SSH keys or recreate the machine with `docker-machine rm <machine> && docker-machine create ...`.
Prefer Docker for Desktop / native Docker over docker-machine, or set DOCKER_HOST directly so TestContainers does not take the docker-machine code path.
Upgrade TestContainers — docker-machine support is legacy and newer versions detect the host IP without SSH_CONNECTION.

Example fix

// before (broken docker-machine env)
genericContainer.getTestHostIpAddress();

// after: pre-check the machine is reachable before running tests
assumingThat(isDockerMachineReachable(), () -> {
    String hostIp = genericContainer.getTestHostIpAddress();
});

Defensive patterns

Strategy: validation

Validate before calling

String machine = System.getenv("DOCKER_MACHINE_NAME");
if (machine != null) {
    String out = CommandLine.runShellCommand("docker-machine", "ssh", machine, "echo $SSH_CONNECTION").trim();
    if (out.isEmpty()) throw new SkipException("docker-machine SSH_CONNECTION unavailable; skipping host-IP test");
}

Try / catch

try {
    String ip = container.getTestHostIpAddress();
} catch (IllegalStateException e) {
    Assume.assumeFalse("docker-machine unavailable", e.getMessage().contains("SSH_CONNECTION"));
}

Prevention

Keep the docker-machine VM running (`docker-machine status <machine>`) before the test suite.
Prefer Docker for Desktop/native Docker; avoid the docker-machine code path entirely.
Cache a successful `docker-machine ssh ... echo $SSH_CONNECTION` check in CI setup steps.
Guard tests with Assume/assumeTrue so a broken machine skips rather than fails.

When it happens

Trigger: Calling getTestHostIpAddress() when TestContainers detects the environment variable DOCKER_MACHINE_NAME (a docker-machine default machine) but `docker-machine ssh <machine> echo $SSH_CONNECTION` returns empty output — e.g. docker-machine is broken, the machine is in a bad state, or the SSH session cannot source the SSH_CONNECTION variable.

Common situations: Developers on Mac/Windows with legacy docker-machine toolboxes (pre-Docker-for-Desktop) whose machine was stopped, deleted, or recreated; docker-machine installed but not provisioned correctly; running inside CI images where the docker-machine VM is not started; custom shells where $SSH_CONNECTION is not populated.

Understand the failure class

Background: "environment variable is not set" and "Missing keys in environment" errors: what missing required env var messages mean and how to fix them — 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/6583fa78be1427da. Report an issue: GitHub.

Appendix: source

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

    /**
     * {@inheritDoc}
     */
    @Override
    @Deprecated
    public String getTestHostIpAddress() {
        if (DockerMachineClient.instance().isInstalled()) {
            try {
                Optional<String> defaultMachine = DockerMachineClient.instance().getDefaultMachine();
                if (!defaultMachine.isPresent()) {
                    throw new IllegalStateException("Could not find a default docker-machine instance");
                }

                String sshConnectionString = CommandLine
                    .runShellCommand("docker-machine", "ssh", defaultMachine.get(), "echo $SSH_CONNECTION")
                    .trim();
                if (Strings.isNullOrEmpty(sshConnectionString)) {
                    throw new IllegalStateException(
                        "Could not obtain SSH_CONNECTION environment variable for docker machine " +
                        defaultMachine.get()
                    );
                }

                String[] sshConnectionParts = sshConnectionString.split("\\s");
                if (sshConnectionParts.length != 4) {
                    throw new IllegalStateException(
                        "Unexpected pattern for SSH_CONNECTION for docker machine - expected 'IP PORT IP PORT' pattern but found '" +
                        sshConnectionString +
                        "'"
                    );
                }

                return sshConnectionParts[0];
            } catch (Exception e) {
                throw new RuntimeException(e);
            }

View on GitHub (pinned to 8e549514e3)