[Bug]: testcontainers does not respect environment variable `DOCKER_HOST` on windows 11 or windows server 2025

[linghengqian]

Module

Core

Testcontainers version

1.21.2

Using the latest Testcontainers version?

Yes

Host OS

Windows

Host Arch

x86_64

Docker version

Client:
 Version:           27.5.1
 API version:       1.47
 Go version:        go1.22.11
 Git commit:        9f9e405
 Built:             Wed Jan 22 13:41:44 2025
 OS/Arch:           windows/amd64
 Context:           default
Server: Docker Engine - Community
 Engine:
  Version:          28.3.0
  API version:      1.51 (minimum version 1.24)
  Go version:       go1.24.4
  Git commit:       265f709
  Built:            Tue Jun 24 15:44:12 2025
  OS/Arch:          linux/amd64
  Experimental:     false
 containerd:
  Version:          1.7.27
  GitCommit:        05044ec0a9a75232cad458027ca83437aae3f4da
 runc:
  Version:          1.2.5
  GitCommit:        v1.2.5-0-g59923ef
 docker-init:
  Version:          0.19.0
  GitCommit:        de40ad0

What happened?

• testcontainers does not respect environment variable DOCKER_HOST on windows 11 or windows server 2025. I created minimal unit tests at https://github.com/linghengqian/windows-env-testcontainers-test , and a corresponding github actions pipeline with no GUI operations.
• Long story short, I want to start WSL2 on the windows runner on github actions and set up the Docker CLI on windows to connect to the Docker daemon on the linux distribution of WSL2 so that testcontainers-java can run Linux Containers.
• For https://github.com/linghengqian/windows-env-testcontainers-test/blob/master/.github/workflows/test.yml and https://github.com/linghengqian/windows-env-testcontainers-test/actions/runs/15953082853/job/44995706464 , I can execute docker run hello-world:linux on windows normally, but testcontainers-java ignores the environment variable DOCKER_HOST, resulting in unit test execution failure.

name: Test CI

on:
  push:
    branches: [ master ]
  workflow_dispatch:
  
concurrency:
  group: test-${{ github.workflow }}-${{ github.ref }}
  cancel-in-progress: true

jobs:
  test:
    runs-on: 'windows-latest'
    timeout-minutes: 60
    steps:
      - uses: actions/checkout@v4
      - name: Setup WSL 2 and Ubuntu Linux distribution
        uses: Vampire/setup-wsl@v5
        with:
          distribution: 'Ubuntu-24.04'
          use-cache: 'true'
      - name: Setup Docker daemon on Linux distribution on WSL without GUI
        shell: wsl-bash {0}
        run: |
          sudo apt-get update
          sudo apt-get remove docker.io docker-doc docker-compose docker-compose-v2 podman-docker containerd runc
          sudo apt-get install ca-certificates curl -y
          sudo install -m 0755 -d /etc/apt/keyrings
          sudo curl -fsSL https://download.docker.com/linux/ubuntu/gpg -o /etc/apt/keyrings/docker.asc
          sudo chmod a+r /etc/apt/keyrings/docker.asc
          echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.asc] https://download.docker.com/linux/ubuntu $(. /etc/os-release && echo "$VERSION_CODENAME") stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null
          sudo apt-get update
          sudo apt-get install docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin -y
          sudo sed -i 's|-H fd://|-H fd:// -H tcp://127.0.0.1:12375|' /usr/lib/systemd/system/docker.service
          sudo systemctl daemon-reload
          sudo systemctl restart docker.service
      - name: Test Docker CLI on Windows Server without GUI
        env:
          DOCKER_HOST: tcp://127.0.0.1:12375
        run: |
          docker version
          docker run hello-world:linux
      - uses: actions/setup-java@v4
        with:
          distribution: 'microsoft'
          java-version: '21'
          cache: 'maven'
      - name: Run test with JDK
        env:
          DOCKER_HOST: tcp://127.0.0.1:12375
        run: ./mvnw clean test

• I introduced another operation when you have access to the windows GUI at https://github.com/linghengqian/windows-env-testcontainers-test/blob/master/README.md . I know I can solve this problem directly by installing Docker Desktop or Rancher Desktop. But the problem is that there is no GUI in github actions, and I can't install Docker Desktop or Rancher Desktop. I have to manually configure the Docker CLI and Docker Daemon on WSL2.

Relevant log output

[INFO] 
[INFO] -------------------------------------------------------
[INFO]  T E S T S
[INFO] -------------------------------------------------------
[INFO] Running io.github.linghengqian.SimpleTest
07:56:30.661 [main] INFO  org.testcontainers.images.PullPolicy - Image pull policy will be performed by: DefaultPullPolicy()
07:56:30.677 [main] INFO  org.testcontainers.utility.ImageNameSubstitutor - Image name substitution will be performed by: DefaultImageNameSubstitutor (composite of 'ConfigurationFileImageNameSubstitutor' and 'PrefixingImageNameSubstitutor')
07:56:30.724 [main] INFO  org.testcontainers.DockerClientFactory - Testcontainers version: 1.21.2
07:56:30.943 [main] WARN  org.testcontainers.dockerclient.DockerClientProviderStrategy - DOCKER_HOST tcp://127.0.0.1:12375 is not listening
java.net.ConnectException: Connection refused: connect
	at java.base/sun.nio.ch.Net.connect0(Native Method)
	at java.base/sun.nio.ch.Net.connect(Net.java:589)
	at java.base/sun.nio.ch.Net.connect(Net.java:578)
	at java.base/sun.nio.ch.NioSocketImpl.connect(NioSocketImpl.java:583)
	at java.base/java.net.SocksSocketImpl.connect(SocksSocketImpl.java:327)
	at java.base/java.net.Socket.connect(Socket.java:751)
	at java.base/java.net.Socket.connect(Socket.java:686)
	at org.testcontainers.dockerclient.DockerClientProviderStrategy.lambda$test$3(DockerClientProviderStrategy.java:214)
	at org.testcontainers.shaded.org.awaitility.core.AssertionCondition.lambda$new$0(AssertionCondition.java:53)
	at org.testcontainers.shaded.org.awaitility.core.ConditionAwaiter$ConditionPoller.call(ConditionAwaiter.java:248)
	at org.testcontainers.shaded.org.awaitility.core.ConditionAwaiter$ConditionPoller.call(ConditionAwaiter.java:235)
	at java.base/java.util.concurrent.FutureTask.run(FutureTask.java:317)
	at java.base/java.util.concurrent.ThreadPoolExecutor.runWorker(ThreadPoolExecutor.java:1144)
	at java.base/java.util.concurrent.ThreadPoolExecutor$Worker.run(ThreadPoolExecutor.java:642)
	at java.base/java.lang.Thread.run(Thread.java:1583)
07:56:31.161 [main] INFO  org.testcontainers.dockerclient.DockerClientProviderStrategy - Found Docker environment with local Npipe socket (npipe:////./pipe/docker_engine)
07:56:31.161 [main] WARN  org.testcontainers.dockerclient.DockerClientProviderStrategy - windows is currently not supported
07:56:31.176 [main] INFO  org.testcontainers.dockerclient.DockerMachineClientProviderStrategy - docker-machine executable was not found on PATH ([C:\Program Files\PowerShell\7, C:\hostedtoolcache\windows\Java_Microsoft_jdk\21.0.2\x64\bin, D:\a\_temp\wsl-shell-wrapper, C:\Program Files\MongoDB\Server\5.0\bin, C:\aliyun-cli, C:\vcpkg, C:\Program Files (x86)\NSIS\, C:\tools\zstd, C:\Program Files\Mercurial\, C:\hostedtoolcache\windows\stack\3.5.1\x64, C:\cabal\bin, C:\\ghcup\bin, C:\mingw64\bin, C:\Program Files\dotnet, C:\Program Files\MySQL\MySQL Server 8.0\bin, C:\Program Files\R\R-4.4.2\bin\x64, C:\SeleniumWebDrivers\GeckoDriver, C:\SeleniumWebDrivers\EdgeDriver\, C:\SeleniumWebDrivers\ChromeDriver, C:\Program Files (x86)\sbt\bin, C:\Program Files (x86)\GitHub CLI, C:\Program Files\Git\bin, C:\Program Files (x86)\pipx_bin, C:\npm\prefix, C:\hostedtoolcache\windows\go\1.24.4\x64\bin, C:\hostedtoolcache\windows\Python\3.9.13\x64\Scripts, C:\hostedtoolcache\windows\Python\3.9.13\x64, C:\hostedtoolcache\windows\
07:56:31.176 [main] ERROR org.testcontainers.dockerclient.DockerClientProviderStrategy - Could not find a valid Docker environment. Please check configuration. Attempted configurations were:
	NpipeSocketClientProviderStrategy: failed with exception InvalidConfigurationException (windows containers are currently not supported)As no valid configuration was found, execution cannot continue.
See https://java.testcontainers.org/on_failure.html for more details.
Error:  Tests run: 1, Failures: 0, Errors: 1, Skipped: 0, Time elapsed: 0.703 s <<< FAILURE! -- in io.github.linghengqian.SimpleTest
Error:  io.github.linghengqian.SimpleTest.testContainers -- Time elapsed: 0.687 s <<< ERROR!
java.lang.IllegalStateException: Could not find a valid Docker environment. Please see logs and check configuration
	at org.testcontainers.dockerclient.DockerClientProviderStrategy.lambda$getFirstValidStrategy$7(DockerClientProviderStrategy.java:274)
	at java.base/java.util.Optional.orElseThrow(Optional.java:403)
	at org.testcontainers.dockerclient.DockerClientProviderStrategy.getFirstValidStrategy(DockerClientProviderStrategy.java:265)
	at org.testcontainers.DockerClientFactory.getOrInitializeStrategy(DockerClientFactory.java:154)
	at org.testcontainers.DockerClientFactory.client(DockerClientFactory.java:196)
	at org.testcontainers.DockerClientFactory$1.getDockerClient(DockerClientFactory.java:108)
	at com.github.dockerjava.api.DockerClientDelegate.authConfig(DockerClientDelegate.java:109)
	at org.testcontainers.containers.GenericContainer.start(GenericContainer.java:321)
	at io.github.linghengqian.SimpleTest.testContainers(SimpleTest.java:16)
	at java.base/java.lang.reflect.Method.invoke(Method.java:580)
	at java.base/java.util.ArrayList.forEach(ArrayList.java:1596)
	at java.base/java.util.ArrayList.forEach(ArrayList.java:1596)
[INFO] 
[INFO] Results:
[INFO] 
Error:  Errors: 
Error:    SimpleTest.testContainers:16 � IllegalState Could not find a valid Docker environment. Please see logs and check configuration
[INFO] 
Error:  Tests run: 1, Failures: 0, Errors: 1, Skipped: 0
[INFO] 
[INFO] ------------------------------------------------------------------------
[INFO] BUILD FAILURE
[INFO] ------------------------------------------------------------------------
[INFO] Total time:  10.818 s
[INFO] Finished at: 2025-06-29T07:56:31Z
[INFO] ------------------------------------------------------------------------
Error:  Failed to execute goal org.apache.maven.plugins:maven-surefire-plugin:3.2.5:test (default-test) on project windows-env-testcontainers-test: 
Error:  
Error:  Please refer to D:\a\windows-env-testcontainers-test\windows-env-testcontainers-test\target\surefire-reports for the individual test results.
Error:  Please refer to dump files (if any exist) [date].dump, [date]-jvmRun[N].dump and [date].dumpstream.
Error:  -> [Help 1]
Error:  
Error:  To see the full stack trace of the errors, re-run Maven with the -e switch.
Error:  Re-run Maven using the -X switch to enable full debug logging.
Error:  
Error:  For more information about the errors and possible solutions, please read the following articles:
Error:  [Help 1] http://cwiki.apache.org/confluence/display/MAVEN/MojoFailureException
Error: Process completed with exit code 1.

Additional Information

• Early investigation came from Support running nativeTest under GraalVM Native Image on Windows 11 apache/shardingsphere#35052 .

[eddumelendez]

Could you try adding a ~/.testcontainers.properties with

docker.client.strategy=org.testcontainers.dockerclient.EnvironmentAndSystemPropertyClientProviderStrategy

and run it again, please?

NpipeSocketClientProviderStrategy is used because you are running on windows host.

[jaroszan]

Any news on this issue? Having very similar one.

I have tried suggestion by @eddumelendez and nothing changed.

[linghengqian]

Oops, outlook.com categorized the notification email for this issue into spam; I just saw the message now.

and run it again, please?
NpipeSocketClientProviderStrategy is used because you are running on windows host.

@eddumelendez I believe that simply adding testcontainers.properties to the classpath will also reproduce the bug.

I did the test at https://github.com/linghengqian/windows-env-testcontainers-test/actions/runs/23893591550/job/69672686099 . However, the corresponding CI still failed. You can see the details at https://github.com/linghengqian/windows-env-testcontainers-test .

[INFO] 
[INFO] -------------------------------------------------------
[INFO]  T E S T S
[INFO] -------------------------------------------------------
[INFO] Running io.github.linghengqian.SimpleTest
09:25:38.920 [main] INFO  org.testcontainers.images.PullPolicy - Image pull policy will be performed by: DefaultPullPolicy()
09:25:38.926 [main] INFO  org.testcontainers.utility.ImageNameSubstitutor - Image name substitution will be performed by: DefaultImageNameSubstitutor (composite of 'ConfigurationFileImageNameSubstitutor' and 'PrefixingImageNameSubstitutor')
09:25:38.982 [main] INFO  org.testcontainers.DockerClientFactory - Testcontainers version: 1.21.4
09:25:39.219 [main] WARN  org.testcontainers.dockerclient.DockerClientProviderStrategy - DOCKER_HOST tcp://127.0.0.1:12375 is not listening
java.net.ConnectException: Connection refused: connect
	at java.base/sun.nio.ch.Net.connect0(Native Method)
	at java.base/sun.nio.ch.Net.connect(Net.java:589)
	at java.base/sun.nio.ch.Net.connect(Net.java:578)
	at java.base/sun.nio.ch.NioSocketImpl.connect(NioSocketImpl.java:583)
	at java.base/java.net.SocksSocketImpl.connect(SocksSocketImpl.java:327)
	at java.base/java.net.Socket.connect(Socket.java:751)
	at java.base/java.net.Socket.connect(Socket.java:686)
	at org.testcontainers.dockerclient.DockerClientProviderStrategy.lambda$test$3(DockerClientProviderStrategy.java:214)
	at org.testcontainers.shaded.org.awaitility.core.AssertionCondition.lambda$new$0(AssertionCondition.java:53)
	at org.testcontainers.shaded.org.awaitility.core.ConditionAwaiter$ConditionPoller.call(ConditionAwaiter.java:248)
	at org.testcontainers.shaded.org.awaitility.core.ConditionAwaiter$ConditionPoller.call(ConditionAwaiter.java:235)
	at java.base/java.util.concurrent.FutureTask.run(FutureTask.java:317)
	at java.base/java.util.concurrent.ThreadPoolExecutor.runWorker(ThreadPoolExecutor.java:1144)
	at java.base/java.util.concurrent.ThreadPoolExecutor$Worker.run(ThreadPoolExecutor.java:642)
	at java.base/java.lang.Thread.run(Thread.java:1583)
09:25:39.466 [main] INFO  org.testcontainers.dockerclient.DockerClientProviderStrategy - Found Docker environment with local Npipe socket (npipe:////./pipe/docker_engine)
09:25:39.466 [main] WARN  org.testcontainers.dockerclient.DockerClientProviderStrategy - windows is currently not supported
09:25:39.474 [main] INFO  org.testcontainers.dockerclient.DockerMachineClientProviderStrategy - docker-machine executable was not found on PATH ([C:\Program Files\PowerShell\7, C:\hostedtoolcache\windows\Java_Microsoft_jdk\21.0.2\x64\bin, D:\a\_temp\wsl-shell-wrapper, C:\Program Files\MongoDB\Server\7.0\bin, C:\vcpkg, C:\tools\zstd, C:\hostedtoolcache\windows\stack\3.9.3\x64, C:\cabal\bin, C:\\ghcup\bin, C:\mingw64\bin, C:\Program Files\dotnet, C:\Program Files\MySQL\MySQL Server 8.0\bin, C:\Program Files\R\R-4.5.3\bin\x64, C:\SeleniumWebDrivers\GeckoDriver, C:\SeleniumWebDrivers\EdgeDriver\, C:\SeleniumWebDrivers\ChromeDriver, C:\Program Files (x86)\sbt\bin, C:\Program Files (x86)\GitHub CLI, C:\Program Files\Git\bin, C:\Program Files (x86)\pipx_bin, C:\npm\prefix, C:\hostedtoolcache\windows\go\1.24.13\x64\bin, C:\hostedtoolcache\windows\Python\3.12.10\x64\Scripts, C:\hostedtoolcache\windows\Python\3.12.10\x64, C:\hostedtoolcache\windows\Ruby\3.3.10\x64\bin, C:\Program Files\OpenSSL\bin, C:\tools\kotlinc\bin, C:\hostedtoolcache\windows\Java_Temurin-Hotspot_jdk\17.0.18-8\x64\bin, C:\Program Files\ImageMagick-7.1.2-Q16-HDRI, C:\Program Files\Microsoft SDKs\Azure\CLI2\wbin, C:\ProgramData\kind, C:\ProgramData\Chocolatey\bin, C:\Windows\system32, C:\Windows, C:\Windows\System32\Wbem, C:\Windows\System32\WindowsPowerShell\v1.0\, C:\Windows\System32\OpenSSH\, C:\Program Files\PowerShell\7\, C:\Program Files\Microsoft\Web Platform Installer\, C:\Program Files\Microsoft SQL Server\Client SDK\ODBC\170\Tools\Binn\, C:\Program Files\Microsoft SQL Server\150\Tools\Binn\, C:\Program Files\dotnet\, C:\Program Files (x86)\Windows Kits\10\Windows Performance Toolkit\, C:\Program Files (x86)\WiX Toolset v3.14\bin, C:\Program Files\Microsoft SQL Server\130\DTS\Binn\, C:\Program Files\Microsoft SQL Server\140\DTS\Binn\, C:\Program Files\Microsoft SQL Server\150\DTS\Binn\, C:\Program Files\Microsoft SQL Server\160\DTS\Binn\, C:\Program Files\Microsoft SQL Server\170\DTS\Binn\, C:\ProgramData\chocolatey\lib\pulumi\tools\Pulumi\bin, C:\Program Files\CMake\bin, C:\Strawberry\c\bin, C:\Strawberry\perl\site\bin, C:\Strawberry\perl\bin, C:\ProgramData\chocolatey\lib\maven\apache-maven-3.9.14\bin, C:\Program Files\Microsoft Service Fabric\bin\Fabric\Fabric.Code, C:\Program Files\Microsoft SDKs\Service Fabric\Tools\ServiceFabricLocalClusterManager, C:\Program Files\nodejs\, C:\Program Files\Git\cmd, C:\Program Files\Git\mingw64\bin, C:\Program Files\Git\usr\bin, C:\Program Files\GitHub CLI\, c:\tools\php, C:\Program Files (x86)\sbt\bin, C:\Program Files\Amazon\AWSCLIV2\, C:\Program Files\Amazon\SessionManagerPlugin\bin\, C:\Program Files\Amazon\AWSSAMCLI\bin\, C:\Program Files\Microsoft SQL Server\130\Tools\Binn\, C:\Program Files\mongosh\, C:\Program Files\LLVM\bin, C:\Program Files (x86)\LLVM\bin, C:\Users\runneradmin\.dotnet\tools, C:\Users\runneradmin\.cargo\bin, C:\Users\runneradmin\AppData\Local\Microsoft\WindowsApps])
09:25:39.476 [main] ERROR org.testcontainers.dockerclient.DockerClientProviderStrategy - Could not find a valid Docker environment. Please check configuration. Attempted configurations were:
	NpipeSocketClientProviderStrategy: failed with exception InvalidConfigurationException (windows containers are currently not supported)As no valid configuration was found, execution cannot continue.
See https://java.testcontainers.org/on_failure.html for more details.
Error:  Tests run: 1, Failures: 0, Errors: 1, Skipped: 0, Time elapsed: 0.755 s <<< FAILURE! -- in io.github.linghengqian.SimpleTest
Error:  io.github.linghengqian.SimpleTest.testContainers -- Time elapsed: 0.727 s <<< ERROR!
java.lang.IllegalStateException: Could not find a valid Docker environment. Please see logs and check configuration
	at org.testcontainers.dockerclient.DockerClientProviderStrategy.lambda$getFirstValidStrategy$7(DockerClientProviderStrategy.java:274)
	at java.base/java.util.Optional.orElseThrow(Optional.java:403)
	at org.testcontainers.dockerclient.DockerClientProviderStrategy.getFirstValidStrategy(DockerClientProviderStrategy.java:265)
	at org.testcontainers.DockerClientFactory.getOrInitializeStrategy(DockerClientFactory.java:154)
	at org.testcontainers.DockerClientFactory.client(DockerClientFactory.java:196)
	at org.testcontainers.DockerClientFactory$1.getDockerClient(DockerClientFactory.java:108)
	at com.github.dockerjava.api.DockerClientDelegate.authConfig(DockerClientDelegate.java:109)
	at org.testcontainers.containers.GenericContainer.start(GenericContainer.java:321)
	at io.github.linghengqian.SimpleTest.testContainers(SimpleTest.java:16)
	at java.base/java.lang.reflect.Method.invoke(Method.java:580)
	at java.base/java.util.ArrayList.forEach(ArrayList.java:1596)
	at java.base/java.util.ArrayList.forEach(ArrayList.java:1596)

[INFO] 
[INFO] Results:
[INFO] 
Error:  Errors: 
Error:    SimpleTest.testContainers:16 � IllegalState Could not find a valid Docker environment. Please see logs and check configuration
[INFO] 
Error:  Tests run: 1, Failures: 0, Errors: 1, Skipped: 0
[INFO] 
[INFO] ------------------------------------------------------------------------
[INFO] BUILD FAILURE
[INFO] ------------------------------------------------------------------------
[INFO] Total time:  13.220 s
[INFO] Finished at: 2026-04-02T09:25:40Z
[INFO] ------------------------------------------------------------------------
Error:  Failed to execute goal org.apache.maven.plugins:maven-surefire-plugin:3.2.5:test (default-test) on project windows-env-testcontainers-test: 
Error:  
Error:  Please refer to D:\a\windows-env-testcontainers-test\windows-env-testcontainers-test\target\surefire-reports for the individual test results.
Error:  Please refer to dump files (if any exist) [date].dump, [date]-jvmRun[N].dump and [date].dumpstream.
Error:  -> [Help 1]
Error:  
Error:  To see the full stack trace of the errors, re-run Maven with the -e switch.
Error:  Re-run Maven using the -X switch to enable full debug logging.
Error:  
Error:  For more information about the errors and possible solutions, please read the following articles:
Error:  [Help 1] http://cwiki.apache.org/confluence/display/MAVEN/MojoFailureException
Error: Process completed with exit code 1.

In https://github.com/linghengqian/windows-env-testcontainers-test/blob/master/.github/workflows/test.yml, executing docker run hello-world:linux directly in PowerShell 7 will not result in any errors. I believe there is a problem with the handling of testcontainers-java.