Lỗi này xảy ra khi Docker Desktop trên Windows không kết nối được với WSL2 phía dưới. Nguyên nhân thường gặp nhất: distro đang chạy WSL1 thay vì WSL2, Hyper-V/Virtual Machine Platform chưa được bật, file .wslconfig giới hạn tài nguyên quá chặt, hoặc tiến trình WSL bị treo/crash.

Các bước dưới đây được sắp theo thứ tự từ nhanh nhất đến triệt để nhất — nên thử đúng thứ tự trước khi nghĩ đến việc cài lại từ đầu.

Thử ngay: 4 lệnh thường sửa được luôn

Mở PowerShell (Admin) và chạy lần lượt:

# 1. Tắt toàn bộ WSL, sau đó mở lại Docker Desktop
wsl --shutdown

# 2. Cập nhật WSL lên bản mới nhất
wsl --update
wsl --status

# 3. Khởi động lại service của WSL
Get-Service LxssManager | Restart-Service

# 4. Kiểm tra distro đang chạy WSL2 (không phải WSL1)
wsl --list --verbose

Ở lệnh cuối, kỳ vọng thấy mọi distro — kể cả docker-desktop và docker-desktop-data — có cột VERSION là 2 và STATE là Running. Nếu 4 bước này chưa xử lý được, chuyển sang phần chẩn đoán theo nguyên nhân bên dưới.

Tìm đúng nguyên nhân & Cách xử lý

1. Distro vẫn ở WSL1

Docker Desktop chỉ chạy engine trên WSL2. Chuyển distro sang WSL2:

wsl --set-default-version 2
wsl --set-version Ubuntu-22.04 2

Thay Ubuntu-22.04 bằng tên distro thật của bạn, lấy từ kết quả wsl --list --verbose.

2. Hyper-V / Virtual Machine Platform chưa bật

Bật hai tính năng Windows bắt buộc:

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

Hoặc vào Control Panel → Turn Windows features on or off, tích chọn Virtual Machine Platform, Windows Subsystem for Linux, và Hyper-V (nếu máy chạy bản Pro). Khởi động lại máy sau khi bật.

Kiểm tra ảo hóa CPU đã bật trong BIOS, và hypervisor đang hoạt động:

systeminfo | findstr /i "Virtualization"
bcdedit /enum | findstr /i hypervisorlaunchtype

Nếu hypervisorlaunchtype trả về Off:

bcdedit /set hypervisorlaunchtype Auto

Khởi động lại máy sau khi chạy lệnh này.

3. File .wslconfig giới hạn RAM/CPU quá chặt

Mở C:\Users\<User>\.wslconfig. Nếu file này tồn tại, xóa hoặc chỉnh lại các dòng giới hạn memory / processors. Rất nhiều trường hợp Docker khởi động lại được ngay sau khi xóa file này.

4. Distro nằm ở ổ khác ổ C, hoặc bị nén

WSL chỉ chạy ổn định khi cài trên ổ hệ thống và không bị nén. Chuột phải vào thư mục LocalState của distro → Properties → Advanced, đảm bảo bỏ tích Compress contents to save disk space.

5. WSL hoặc Docker Desktop đang chạy bản có bug

Cập nhật cả hai lên bản mới nhất. Nếu lỗi chỉ xuất hiện sau một lần update WSL gần đây, nhiều khả năng đây là bug riêng của bản đó — kiểm tra GitHub issues của Microsoft/WSL trước khi quyết định rollback.

6. Không chạy quyền Admin, hoặc “Use legacy console” đang bật

Mở Docker Desktop bằng quyền Administrator. Nếu dùng Windows Terminal hoặc CMD, tắt Use legacy console trong Properties của terminal.

7. Proxy / Firewall / VPN chặn kết nối

Tắt proxy tạm thời, hoặc khai đúng biến HTTP_PROXY / NO_PROXY. Đảm bảo firewall cho phép WSL truy cập mạng. VPN doanh nghiệp (như Cisco AnyConnect) thường phá route mạng của WSL — thử tắt VPN để loại trừ nguyên nhân này.

Nếu nghi do DNS/Winsock:

netsh winsock reset

Khởi động lại máy sau khi chạy lệnh trên.

8. Xung đột với VMware / VirtualBox

Cập nhật VirtualBox lên bản ≥ 6.1 hoặc VMware ≥ 15.5 — các bản này chạy song song được với Hyper-V. Nếu vẫn xung đột, tạm tắt hoặc gỡ phần mềm đó trong lúc cần chạy Docker.

Vẫn không được? Backup rồi cài lại từ đầu

Trước khi gỡ cài đặt, luôn sao lưu dữ liệu quan trọng trước.

Backup images/containers:

docker container commit my_container my_backup_image
docker save my_backup_image -o my_backup_image.tar

Backup volumes (dùng container tạm để đóng gói lại thành tar):

docker run --rm -v my_volume:/vol -v C:\backup:/backup ubuntu tar czvf /backup/my_volume.tar /vol

Nếu Docker Desktop không mở lên được để chạy các lệnh trên, sao lưu trực tiếp file VM bằng cách copy %LOCALAPPDATA%\Docker\wsl\data\docker_data.vhdx sang một nơi an toàn.

Gỡ và cài lại WSL:

wsl --unregister Legacy    # nếu còn distro WSL1 cũ, thay "Legacy" bằng tên distro đó
wsl --uninstall
wsl --install -d Ubuntu-22.04
wsl --set-default-version 2

Cài lại Docker Desktop:

  1. Gỡ qua Settings → Apps.
  2. Xóa sạch thêm hai thư mục %APPDATA%\Docker và %LocalAppData%\Docker.
  3. Tải bản mới nhất từ trang chủ Docker và mở bằng quyền Admin.
  4. Nếu vẫn lỗi, dùng Troubleshoot → Reset to factory defaults ngay trong Docker Desktop (Lưu ý: bước này xóa hết container/image hiện có, chỉ thực hiện sau khi đã backup xong).

Khôi phục dữ liệu: Copy file docker_data.vhdx đã backup trở lại đúng vị trí cũ, hoặc nạp lại image đã lưu bằng docker load -i my_backup_image.tar.

Xác nhận đã hết lỗi

docker run --rm hello-world
wsl --list --verbose
docker info
docker volume ls

Mọi thứ ổn khi: hello-world chạy thành công, tất cả distro ở VERSION 2 và Running, docker info báo Engine là Docker Desktop / OS là Linux, và các volume quan trọng vẫn còn nguyên.

Để tránh lặp lại

  • Để Docker Desktop và WSL tự cập nhật, hoặc chạy wsl --update định kỳ.
  • Không giới hạn RAM/CPU trong .wslconfig quá thấp nếu không thật cần thiết.
  • Backup định kỳ bằng wsl --export, đừng chờ đến lúc lỗi mới backup.
  • Tránh chạy song song hai tầng ảo hóa không tương thích.
  • Cập nhật Windows Update và driver CPU (Intel/AMD) đầy đủ.

Sơ đồ xử lý nhanh

Lỗi: WSL terminated
       │
       ├─── Chưa bật WSL2/Hyper-V? → Bật Virtual Machine Platform + WSL → Restart
       │
       ├─── Distro ở WSL1? → wsl --set-version 2 → Restart
       │
       ├─── .wslconfig giới hạn tài nguyên? → Xóa/Sửa → wsl --shutdown
       │
       ├─── Proxy/Firewall/VPN? → Tắt tạm thời → Test lại
       │
       ├─── Xung đột VMware/VirtualBox? → Update hoặc tắt tạm
       │
       └─── Vẫn lỗi? → Backup → Cài lại WSL + Docker Desktop → Restore

Nguồn tham khảo: Tổng hợp từ tài liệu chính thức của Docker và Microsoft WSL về WSL2, kết hợp các cách xử lý đã được cộng đồng (GitHub issues, StackOverflow) xác nhận có hiệu quả.