Skip to content

HT-014 — Windows Service Management (WSL2 + Docker)

Purpose

Document the known Windows-side service management issues affecting the Atlantis stack on Trunks, including the critical WSL2 VHDX ACL fix triggered by Docker Desktop reinstalls.

Primary issue covered: Docker Desktop reinstall silently wipes WSL2 virtual disk permissions, causing E_ACCESSDENIED on WSL2 launch. This is a repeatable, documented failure mode that will recur on every Docker Desktop reinstall.

Overview

Issue Trigger Impact Fix Time
VHDX ACL wiped Docker Desktop reinstall WSL2 won't launch ~5 min
WSL2 process lock Docker holding HCS handle WSL2 mount fails ~2 min
PM2 services down WSL2 restart All Nova services offline ~1 min
Docker WSL integration conflict Docker Desktop update WSL2 blocked ~5 min

Issue 1 — WSL2 VHDX Access Denied (Critical)

Symptom

After installing or reinstalling Docker Desktop, WSL2 fails to launch:

Failed to attach disk 'C:\Users\Shane\AppData\Local\wsl\{GUID}\ext4.vhdx' to WSL2: Access is denied.
Error code: Wsl/Service/CreateInstance/MountDisk/HCS/E_ACCESSDENIED

This persists through reboots.

Root Cause

Docker Desktop's installer silently removes all Access Control List (ACL) entries from the WSL2 virtual disk file (ext4.vhdx). With no ACL entries, the Windows Hyper-V Compute Service (HCS) has no authorization to mount the disk.

Diagnosis

Confirm ACL is empty (run PowerShell as Administrator):

$vhdx = "C:\Users\Shane\AppData\Local\wsl\{GUID}\ext4.vhdx"
# Replace {GUID} with actual folder name — check AppData\Local\wsl\
Test-Path $vhdx
(Get-Acl $vhdx).Access | Select IdentityReference, FileSystemRights, AccessControlType

If ACL query returns nothing (empty) → this is the issue.

Find your actual VHDX path: 

Get-ChildItem "$env:LOCALAPPDATA\wsl\" -Recurse -Filter "ext4.vhdx" | Select FullName

Fix

Run in PowerShell as Administrator:

# 1. Set your VHDX path
$vhdx = "C:\Users\Shane\AppData\Local\wsl\{GUID}\ext4.vhdx"

# 2. Take ownership
takeown /F $vhdx /A

# 3. Restore ACL entries
$acl = Get-Acl $vhdx

# Grant Shane FullControl
$userRule = New-Object System.Security.AccessControl.FileSystemAccessRule(
    "Shane", "FullControl", "Allow"
)
$acl.SetAccessRule($userRule)

# Grant SYSTEM FullControl (HCS runs as SYSTEM)
$sysRule = New-Object System.Security.AccessControl.FileSystemAccessRule(
    "SYSTEM", "FullControl", "Allow"
)
$acl.SetAccessRule($sysRule)

# Apply
Set-Acl $vhdx $acl

# 4. Verify ACL restored
(Get-Acl $vhdx).Access | Select IdentityReference, FileSystemRights, AccessControlType

Expected output after fix: 

IdentityReference    FileSystemRights  AccessControlType
-----------------    ----------------  -----------------
BUILTIN\Shane        FullControl       Allow
NT AUTHORITY\SYSTEM  FullControl       Allow

Verify WSL2 Launches

wsl --shutdown
wsl -d Ubuntu

Should boot to Ubuntu prompt: 

shane@Trunks:~$

Prevention

After any Docker Desktop install or reinstall:

  1. Run wsl -d Ubuntu immediately to test
  2. If E_ACCESSDENIED → run the ACL fix above
  3. Takes 5 minutes — do not reboot hoping it fixes itself (it won't)

Issue 2 — Docker HCS Process Lock

Symptom

WSL2 throws E_ACCESSDENIED or hangs even with correct ACL. Docker processes are holding an HCS handle on the VHDX.

Fix

Run in PowerShell as Administrator:

# Kill all Docker processes
Get-Process "*docker*" | Stop-Process -Force -ErrorAction SilentlyContinue
Get-Process "*com.docker*" | Stop-Process -Force -ErrorAction SilentlyContinue

# Stop Docker service
Stop-Service "com.docker.service" -Force -ErrorAction SilentlyContinue

# Kill HCS worker processes
Get-Process "vmwp" | Stop-Process -Force -ErrorAction SilentlyContinue
Get-Process "vmmem" | Stop-Process -Force -ErrorAction SilentlyContinue

# Shutdown WSL
wsl --shutdown

# Wait for HCS to release
Start-Sleep -Seconds 8

# Retry
wsl -d Ubuntu

Issue 3 — Docker WSL2 Integration Conflict

Symptom

Docker Desktop installs its own WSL2 distros (docker-desktop, docker-desktop-data) that compete with Ubuntu for the HCS lock.

Diagnosis

wsl --list --verbose

If you see: 

NAME                   STATE           VERSION
* Ubuntu               Stopped         2
  docker-desktop       Running         2
  docker-desktop-data  Running         2

Docker distros are holding resources Ubuntu needs.

Fix

  1. Open Docker Desktop → Settings → Resources → WSL Integration
  2. Uncheck "Enable integration with my default WSL distro"
  3. Uncheck all listed distros
  4. Click Apply & Restart
  5. Run wsl --shutdown then wsl -d Ubuntu
  6. Once Ubuntu confirms launching → re-enable Docker WSL integration

Issue 4 — PM2 Services After WSL2 Restart

Symptom

After WSL2 restarts (shutdown + relaunch), PM2 services may not auto-start.

Check PM2 State

pm2 list

If services show stopped or are missing:

pm2 resurrect

If resurrection fails:

pm2 start ecosystem.config.js
# OR manually restart each service
pm2 start forgejo --name "forgejo"
pm2 start n8n --name "n8n" -- start
pm2 start ~/atlantis/atlantis-job-engine/index.js --name "atlantis-job-engine"
pm2 start ~/atlantis/atlantis-ops/index.js --name "atlantis-ops"
pm2 save

Verify All Services

pm2 list

Expected Trunks PM2 stack:

ID Name Status Port Memory
0 forgejo online 3010 ~181mb
1 atlantis-job-engine online 3005 ~70mb
2 atlantis-ops online — ~70mb
3 n8n online 5678 ~85mb

Total: ~408mb RAM

Quick Reference — Common PowerShell Commands

Run these from PowerShell as Administrator:

# Check WSL distros and state
wsl --list --verbose

# Check WSL version
wsl --version

# Shutdown all WSL instances
wsl --shutdown

# Launch Ubuntu
wsl -d Ubuntu

# Check Windows Optional Features
Get-WindowsOptionalFeature -Online -FeatureName VirtualMachinePlatform
Get-WindowsOptionalFeature -Online -FeatureName Microsoft-Windows-Subsystem-Linux

# Check VHDX exists
Test-Path "C:\Users\Shane\AppData\Local\wsl\{GUID}\ext4.vhdx"

# Check VHDX ACL
(Get-Acl "C:\Users\Shane\AppData\Local\wsl\{GUID}\ext4.vhdx").Access | Select IdentityReference, FileSystemRights

Troubleshooting Decision Tree

WSL2 won't launch?
    │
    ├── E_ACCESSDENIED error?
    │       │
    │       ├── ACL empty? → Run Issue 1 fix (VHDX ACL restore)
    │       └── ACL present? → Run Issue 2 fix (kill Docker processes)
    │
    ├── Hangs forever?
    │       └── Run Issue 2 fix (kill Docker + HCS processes)
    │
    └── docker-desktop distros running?
            └── Run Issue 3 fix (disable Docker WSL integration)
  • HT-011 — Nova-Alpha Quick Access
  • HT-012 — Nova Workspace Structure
  • HT-013 — PM2 Process Manager
  • HT-015 — WSL ↔ Windows Bridge
  • HT-010 — Nova MCP Integration

Revision History

Version Date Author Notes
1.0 2026-04-21 Ozzy Initial — VHDX ACL fix documented after Docker Desktop 4.70.0 incident on Trunks
1.1 2026-04-29 Ozzy Added HCS lock fix, Docker integration conflict, PM2 recovery procedures

End of HT-014 — Windows Service Management (WSL2 + Docker)