testcontainers/testcontainers-java · error · IllegalArgumentException

Unknown transport type

Error message

Unknown transport type '%s'

What it means

Thrown by DockerClientProviderStrategy.getClientForConfig when the selected strategy's TransportConfig reports a docker host whose transport type (scheme) is not one of the supported values (unix, tcp, npipe, http/https). It means the library cannot build an HTTP client for the given dockerHost URI scheme.

Solutions

1. Check DOCKER_HOST and set it to a supported scheme: unix:///var/run/docker.sock, tcp://host:port, or npipe:////./pipe/docker_engine on Windows
2. Print the resolved config (DefaultDockerClientConfig) and inspect the dockerHost URI scheme
3. If using a custom strategy, return a TransportConfig whose dockerHost URI uses a supported scheme
4. Upgrade/align testcontainers versions if a strategy produces a scheme not handled by this core version

Example fix

// before (env)
DOCKER_HOST=sock:///var/run/docker.sock
// after
DOCKER_HOST=unix:///var/run/docker.sock

String dh = System.getenv("DOCKER_HOST");
if (dh != null) {
    java.net.URI uri = java.net.URI.create(dh);
    Set<String> ok = Set.of("unix", "tcp", "npipe", "http", "https");
    if (!ok.contains(uri.getScheme()))
        throw new IllegalStateException("Unsupported DOCKER_HOST scheme: " + uri.getScheme());
}

static boolean isSupportedDockerHost(java.net.URI u) {
    return u != null && Set.of("unix", "tcp", "npipe", "http", "https").contains(u.getScheme());
}

try {
    DockerClient client = DockerClientFactory.instance().client();
} catch (IllegalArgumentException e) {
    if (e.getMessage().contains("Unknown transport type")) {
        // fix or clear DOCKER_HOST and retry with defaults
    } else throw e;
}

When it happens

Trigger: Calling dockerClient() with a strategy/TransportConfig whose dockerHost URI scheme is unrecognized, e.g. DOCKER_HOST set to something like 'foo://...' or a malformed URI, or a custom strategy returning an unsupported transport type.

Common situations: Typo in the DOCKER_HOST scheme in the environment or ~/.testcontainers.properties; a custom TestcontainersConfiguration or client provider strategy returning a hand-built TransportConfig with a wrong scheme; version changes introducing new scheme names.

Understand the failure class

Background: Invalid enum value errors: "Unknown type", "Invalid scope", "must be one of" — when a string is not on the library's allowed list — this error's family across 23 libraries.

Related errors

• Invalid value for dockerconfig.source
• Unexpected scheme
• Previous attempts to find a Docker environment failed. Will…
• containers are currently not supported
• Could not find unix domain socket

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

Appendix: source

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

                );
            })
            .findFirst();
    }

    public static DockerClient getClientForConfig(TransportConfig transportConfig) {
        final DockerHttpClient dockerHttpClient;

        String transportType = TestcontainersConfiguration.getInstance().getTransportType();
        switch (transportType) {
            case "httpclient5":
                dockerHttpClient =
                    new ZerodepDockerHttpClient.Builder()
                        .dockerHost(transportConfig.getDockerHost())
                        .sslConfig(transportConfig.getSslConfig())
                        .build();
                break;
            default:
                throw new IllegalArgumentException("Unknown transport type '" + transportType + "'");
        }

        DefaultDockerClientConfig.Builder configBuilder = DefaultDockerClientConfig
            .createDefaultConfigBuilder()
            .withDockerHost(transportConfig.getDockerHost().toString());

        Map<String, String> headers = new HashMap<>();
        headers.put("x-tc-sid", DockerClientFactory.SESSION_ID);
        headers.put("User-Agent", String.format("tc-java/%s", DockerClientFactory.TESTCONTAINERS_VERSION));

        try {
            if (configBuilder.build().getApiVersion() == RemoteApiVersion.UNKNOWN_VERSION) {
                configBuilder.withApiVersion(RemoteApiVersion.VERSION_1_44);
            }
            DockerClient client = DockerClientImpl.getInstance(
                new AuthDelegatingDockerClientConfig(configBuilder.build()),
                new HeadersAddingDockerHttpClient(dockerHttpClient, headers)
            );

View on GitHub (pinned to 8e549514e3)