Fix Docker Container Not Starting on Windows 11

Windows 11 provides a robust environment for containerized development, primarily through the Windows Subsystem for Linux (WSL 2) backend. However, when Docker Desktop or an individual container suddenly refuses to start, it can bring your local development pipeline to a grinding halt.

Whether you are dealing with a silent crash, a persistent exit code, or a virtualization fault, this troubleshooting guide walks you through diagnosing and resolving container startup failures on Windows 11.

Diagnostic First Steps

Before modifying system configurations or purging data volumes, isolate the failure point. Is the entire Docker engine failing to start, or is it a single container crashing immediately upon execution (exited (1) or exited (137))?

1. Inspect Container Logs

If the container starts and immediately exits, inspect the standard output before the process died.

docker logs <container_name_or_id>

If the container dies too fast for logs to render normally, try running it interactively or overriding the entrypoint to prevent immediate crashing:

docker run -it --entrypoint /bin/sh <image_name>

2. Check Docker Desktop Status and System Events

Open PowerShell as an Administrator and check the Docker daemon status, or inspect the global system events to catch low-level runtime errors:

docker system events

Review the Windows Event Viewer (eventvwr.msc) under Windows Logs > Application and filter by source Docker to identify unhandled exceptions thrown by the daemon.

Fixing Global Docker Daemon Failures on Windows 11

If Docker Desktop itself hangs on "Starting the engine," the underlying Windows virtualization stack or WSL 2 integration is usually the culprit.

1. Restart the Docker Desktop Service

Windows services often hang during sleep/resume cycles. Restart the background services cleanly via PowerShell:

# Stop Docker-related services
Stop-Service com.docker.service
Stop-Service vmcompute

# Start them back up in order
Start-Service vmcompute
Start-Service com.docker.service

2. Verify Hyper-V and WSL 2 Features

Windows 11 requires specific Windows Features enabled at the kernel level. Ensure none of these were disabled by a recent Windows Update.

Open Turn Windows features on or off from the Start Menu.
Ensure the following are checked:
- Virtual Machine Platform
- Windows Subsystem for Linux
- Hyper-V (Available on Windows 11 Pro/Enterprise)

Alternatively, run this PowerShell command as Administrator:

dism.exe /online /enable-feature /featurename:Microsoft-Hyper-V-All /all /norestart
dism.exe /online /enable-feature /featurename:VirtualMachinePlatform /all /norestart
dism.exe /online /enable-feature /featurename:Microsoft-Windows-Subsystem-Linux /all /norestart

Reboot your machine immediately after running these commands.

3. Update the WSL 2 Linux Kernel

Outdated WSL 2 kernels frequently cause daemon initialization timeouts on Windows 11 builds. Update your WSL kernel manually:

wsl --update

Followed by a complete shutdown of all WSL instances:

wsl --shutdown

Resolving Specific Container Startup Errors

If the Docker engine is running fine, but your specific container fails to initialize, the issue typically stems from resource exhaustion, port collisions, volume mounting permissions, or architecture mismatches.

1. Exit Code 137: Out of Memory (OOM)

If your container exits with code 137, the Linux kernel killed the process because it exceeded its allocated memory limit. This is extremely common with resource-heavy local stacks (e.g., Elasticsearch, Kubernetes-in-Docker, large Node.js builds).

Diagnosis: Check if Docker Desktop has enough RAM allocated.
Solution: Open Docker Desktop Settings > Resources > Advanced, and increase the memory slider. Alternatively, configure explicit memory limits in your docker-compose.yml:

services:
  web:
    image: node:18-alpine
    deploy:
      resources:
        limits:
          memory: 2G
        reservations:
          memory: 1G

2. Port Already Allocated (Port Binding Conflicts)

If another process on your Windows host is already binding to the port your container wants to use, startup will fail with an error like: Bind for 0.0.0.0:80 failed: port is already allocated.

Identify the conflicting process in PowerShell:

Get-NetProcess -CimSession . -Id (Get-NetTCPConnection -LocalPort 80).OwningProcess

Kill the offending process or change the port mapping in your container configuration:
```
docker run -d -p 8080:80 nginx
```

3. Volume Mounting and File Permissions (WSL 2 vs. Windows Filesystem)

Cross-file system mounts between the Windows host (C:\...) and the Linux container can cause startup failures, especially for compiled languages or databases that rely on strict file locking and Unix permissions.

Symptom: Node modules failing to load, permission denied errors on /var/lib/mysql, or text file busy errors.
Best Practice: Keep your active source code repositories inside the WSL 2 Linux filesystem (e.g., \\wsl.localhost\Ubuntu\home\user\project) rather than mounting them from the Windows host (C:\projects).
Fixing Volume Mount Syntax: Ensure paths use absolute Linux-style paths in WSL contexts or correct Windows paths:
```
volumes:
  - type: volume
    source: db-data
    target: /var/lib/mysql
```

4. Architecture Mismatch (ARM64 vs. AMD64)

With the rise of ARM64 processors (such as Snapdragon X Elite Windows laptops), running legacy x86_64 images can cause emulation crashes, segmentation faults, or silent failures.

Check your architecture:
```
uname -m
```
Force emulation or target specific platforms in your docker run commands or compose files:
```
docker run --platform linux/amd64 my-legacy-image:latest
```

Resetting and Purging Corrupt States

If standard troubleshooting fails, persistent filesystem corruption inside the Docker virtual disks or WSL distros is often to blame.

1. Prune Unused System Data

Stale build caches, dangling volumes, and stopped containers can choke the storage driver. Clean the slate safely:

# Remove all stopped containers, unused networks, and dangling images
docker system prune -a --volumes

2. Reset WSL 2 Distros

Docker Desktop relies heavily on two hidden WSL distributions: docker-desktop and docker-desktop-data. If these become corrupted, Docker will never start properly.

Shut down WSL completely:
```
wsl --shutdown
```
Unregister the corrupted Docker WSL distributions (Warning: This will wipe local container data stored inside these distros):
```
wsl --unregister docker-desktop
wsl --unregister docker-desktop-data
```
Restart Docker Desktop. It will automatically recreate these instances from scratch.

3. Clean Reinstallation of Docker Desktop

If configuration files in AppData are corrupted:

Uninstall Docker Desktop via Windows Settings.
Manually delete the following directories if they remain:
- C:\Users\<Your-Username>\AppData\Local\Docker
- C:\Users\<Your-Username>\AppData\Roaming\Docker Desktop
Restart your Windows 11 machine.
Download and install the latest stable release of Docker Desktop for Windows. Ensure you check the box to "Enable WSL 2 features" during the installation wizard.

Preventive Best Practices for Developers

To minimize future Docker startup friction on Windows 11, adhere to these operational guidelines:

Keep WSL 2 Updated: Run wsl --update monthly. Windows updates frequently alter Hyper-V hooks that WSL depends on.
Avoid Hybrid Paths: Store your active development projects inside the native WSL filesystem (\\wsl.localhost\<DistroName>\...) instead of heavily mounting deeply nested Windows directories (C:\Users\...).
Configure Resource Caps: Set explicit CPU and Memory ceilings in Docker Desktop Settings to prevent runaway containers from crashing the Windows Hyper-V host service (vmcompute).
Use Healthchecks: Implement native Docker healthchecks in your compose files to gracefully handle startup dependency ordering (e.g., ensuring Postgres is fully ready to accept connections before a Node.js API container boots up).

services:
  database:
    image: postgres:15-alpine
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U postgres"]
      interval: 5s
      timeout: 5s
      retries: 5

  backend:
    build: .
    depends_on:
      database:
        condition: service_healthy

By systematically isolating whether the issue lies in the Windows virtualization layer, the WSL integration, or the container's internal configuration, you can quickly restore your development environment and prevent recurring downtime.