testcontainers/testcontainers-java · warning

Unknown DOCKER_HOST scheme

Error message

Unknown DOCKER_HOST scheme {}, skipping the strategy test...

What it means

Testcontainers saw a DOCKER_HOST URI whose scheme it does not recognize while testing a strategy. Instead of failing, it logs a warning and returns true (assumes the strategy works, skipping the socket reachability check). Common when the scheme is misspelled or an unsupported transport is used.

Solutions

  1. Set DOCKER_HOST to a supported scheme: tcp://host:port, http://, https://, unix:///var/run/docker.sock, or npipe:////./pipe/docker_engine.
  2. Check for typos and casing (`echo $DOCKER_HOST`) and fix the scheme spelling.
  3. If you intended to use Docker over SSH, use a Docker context or an SSH tunnel (e.g. socat/ssh -L to expose a tcp:// endpoint) instead of an ssh:// DOCKER_HOST.
  4. Alternatively let Testcontainers auto-detect the environment by unsetting DOCKER_HOST.

Example fix

// before
DOCKER_HOST=ssh://user@dockerhost
// after
DOCKER_HOST=tcp://localhost:2375  # via `ssh -L 2375:/var/run/docker.sock user@dockerhost`
# or use a supported scheme such as unix:///var/run/docker.sock
Defensive patterns

Strategy: validation

Validate before calling

// Validate the scheme before tests run
String dh = System.getenv("DOCKER_HOST");
if (dh != null) {
    String scheme = java.net.URI.create(dh.trim()).getScheme();
    if (scheme == null || !java.util.Set.of("tcp", "http", "https", "unix", "npipe").contains(scheme.toLowerCase())) {
        throw new IllegalStateException("Unsupported DOCKER_HOST scheme '" + scheme + "' in: " + dh);
    }
}

Prevention

When it happens

Trigger: DOCKER_HOST set to a URI whose scheme is not one of tcp, http, https, unix, or npipe — e.g. `DOCKER_HOST=docker://...`, `DOCKER_HOST=ssh://...`, `DOCKER_HOST=TCP://...` (uppercase), or a typo like `unix:://`.

Common situations: Typo in DOCKER_HOST; copying an ssh:// Docker context URI into DOCKER_HOST (docker-java/Testcontainers do not support ssh transport via scheme); trailing whitespace or uppercase scheme; IDE or CI config exporting a scheme from a non-Docker tool.

Understand the failure class

Background: "Invalid URL" errors: why new URL(), URI.parse, and reqwest::Url reject your string — missing scheme, whitespace, and bad path format — this error's family across 39 libraries.

Related errors

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

Appendix: source

Thrown at core/src/main/java/org/testcontainers/dockerclient/DockerClientProviderStrategy.java:204

                if (!new File(dockerHost.getPath()).exists()) {
                    log.debug("DOCKER_HOST socket file '{}' does not exist", dockerHost.getPath());
                    return false;
                }
                socketProvider =
                    () -> {
                        switch (dockerHost.getScheme()) {
                            case "unix":
                                return UnixSocket.get(dockerHost.getPath());
                            case "npipe":
                                return new NamedPipeSocket(dockerHost.getPath());
                            default:
                                throw new IllegalStateException("Unexpected scheme " + dockerHost.getScheme());
                        }
                    };
                socketAddress = new InetSocketAddress("localhost", 2375);
                break;
            default:
                log.warn("Unknown DOCKER_HOST scheme {}, skipping the strategy test...", dockerHost.getScheme());
                return true;
        }

        try (Socket socket = socketProvider.call()) {
            Awaitility
                .await()
                .atMost(TestcontainersConfiguration.getInstance().getClientPingTimeout(), TimeUnit.SECONDS) // timeout after configured duration
                .pollInterval(Duration.ofMillis(200)) // check state every 200ms
                .pollDelay(Duration.ofSeconds(0)) // start checking immediately
                .untilAsserted(() -> socket.connect(socketAddress));
            return true;
        } catch (Exception e) {
            log.warn("DOCKER_HOST {} is not listening", dockerHost, e);
            return false;
        }
    }

    /**

View on GitHub (pinned to 8e549514e3)