The Desi Architect
Notes / Docker Sandboxes / Windows Troubleshooting for the Labs
Track 06 · Docker Sandboxes · Reference

Windows Troubleshooting for the Labs

The problems Windows learners hit most often, with the exact message you will see and the fix. Most of these we met ourselves while testing the labs on Windows 11 with Docker Desktop. The rest are well known Docker Desktop problems.

Free referenceKeep this tab open while you do a lab

00 /Docker Desktop is not running

You see: cannot connect to the Docker daemon, failed to connect to the docker API at npipe:////./pipe/dockerDesktopLinuxEngine, or The system cannot find the file specified.

Cause: Docker Desktop has to be open and finished starting. The whale icon in the system tray must say it is running, not starting.

Fix: open Docker Desktop, wait a minute until it is running, then check:

docker info

If docker info prints two sections, Client and Server, you are ready.

01 /WSL2 or virtualization is missing

You see: Docker Desktop says WSL 2 is not installed, or that virtualization is disabled.

Fix: in an administrator PowerShell run wsl --install, then restart. If it still complains, turn on virtualization (Intel VT-x or AMD-V) in the BIOS settings of your laptop. Then run wsl --update and start Docker Desktop again.

02 /python3 opens the Microsoft Store

You see: typing python3 opens the Microsoft Store, or prints nothing.

Cause: Windows ships a shortcut called python3 that is not Python.

Fix: use python or py instead. To remove the shortcut: Settings, Apps, Advanced app settings, App execution aliases, and switch off the python.exe and python3.exe entries. The lab .ps1 runners already pick python or py for you.

03 /curl prints something strange

You see: curl in PowerShell asks about "script execution", prints a wall of HTML, or rejects -X and -H.

Cause: in PowerShell, curl is a nickname for a different command, Invoke-WebRequest.

Fix: type curl.exe. When you send JSON, put a backslash before each inner double quote: curl.exe -X POST URL -d '{\"name\":\"asha\"}'.

04 /Git Bash rewrites my paths

You see: ls: C:/Program Files/Git/app: No such file or directory when you meant /app inside a container.

Cause: Git Bash turns paths that start with / into Windows paths before Docker sees them.

Fix: put MSYS_NO_PATHCONV=1 in front of the command, or use PowerShell. The lab .sh runners already do this.

05 /A .sh script fails with strange errors

You see: bad interpreter, \r: command not found, or unexpected end of file.

Cause: the file got Windows line endings (CRLF). Shell scripts need Unix line endings (LF).

Fix: the downloaded zip has the right endings. If you copied files through Git with auto conversion, run git config --global core.autocrlf input, check the files out again, or convert one file with dos2unix test.sh. In VS Code you can also click CRLF at the bottom right and switch it to LF.

06 /PowerShell refuses to run a script

You see: running scripts is disabled on this system or cannot be loaded because running scripts is disabled.

Fix: run the script for this one time with a bypass:

powershell -ExecutionPolicy Bypass -File .\test-basics.ps1

Or allow signed and local scripts for your own user: Set-ExecutionPolicy -Scope CurrentUser RemoteSigned.

07 /A port is already in use

You see: port is already allocated or bind: address already in use.

Fix: find who has it. Replace 18110 with your port:

netstat -ano | findstr :18110
docker ps --format "{{.Names}}  {{.Ports}}"

Usually it is a container from another lab that is still running. Go to that lab's folder and run docker compose down -v. If a Windows program owns the port, close it or change the port number on the left side of ports: in docker-compose.yml.

Windows can also reserve whole ranges of ports for itself. See them with netsh interface ipv4 show excludedportrange protocol=tcp. If your lab port falls inside a range, pick another.

08 /Containers get killed or Docker is very slow

You see: a container in state Exited (137), or Docker Desktop becomes slow when you start Kafka or Elasticsearch.

Cause: the labs that use Kafka or Elasticsearch need about 1 GB or more. WSL2 only gives Docker part of your RAM by default.

Fix: close other heavy programs, and give WSL2 more memory. Create or edit .wslconfig in your user folder (C:\Users\<you>\.wslconfig):

[wsl2]
memory=6GB
swap=2GB

Then run wsl --shutdown and start Docker Desktop again. Pick a number that leaves at least 4 GB for Windows itself.

09 /An image cannot be downloaded

You see: failed to resolve reference, i/o timeout, or toomanyrequests.

Fix: check your internet connection and VPN first. A company network may need a proxy: Docker Desktop, Settings, Resources, Proxies. For toomanyrequests, sign in to Docker Hub with docker login (a free account is enough) and try again. Test with:

docker pull python:3.11-alpine

10 /Folder and file name problems

  • Unzip each lab into its own new folder and open the terminal inside it. "no configuration file provided" means you are in the wrong folder.
  • Keep the folder path short and without special characters, for example C:\labs\docker-basics.
  • If you unzipped on a synced folder (OneDrive), files may be locked. Move the lab to a plain local folder.

11 /Mac with Apple Silicon (M1 to M4)

All images in these labs have both Intel and Apple Silicon versions, so they run natively. If you ever see exec format error or no matching manifest for linux/arm64, tell us which lab and image. As a workaround you can add platform: linux/amd64 to that service in docker-compose.yml, which runs it under emulation more slowly.