Windows Installation Troubleshooting

Common errors you may encounter during installation and how to fix them.

Issue 1: WSL features were enabled but WSL is still not ready

Windows has enabled the WSL feature, but the WSL kernel hasn't finished updating yet.

Fix:

Open PowerShell as Administrator and run:

wsl --update

Wait for the update to complete. If you see the following prompt:

wsl: WSL installation appears to be corrupted (error code: Wsl/CallMsi/Install/REGDB_E_CLASSNOTREG).
Press any key to repair WSL, or CTRL-C to cancel.
This prompt will time out in 60 seconds.

Press any key and wait for the repair to finish.

Once the update finishes, run the following to confirm WSL is ready:

wsl --status

Then relaunch the OpenClacky installer and retry.

Issue 2: Cannot attach virtual disk — Error code Wsl/Service/CreateInstance/MountDisk/HCS/ERRORFILENOT_FOUND

The WSL2 virtual disk file (ext4.vhdx) is missing or corrupted, preventing the distribution from starting.

Fix:

Open PowerShell as Administrator and run:

wsl --unregister Ubuntu

⚠️ Warning: This permanently deletes all data inside the distribution. If you previously installed Ubuntu and have important files, back them up first. If you have never installed Ubuntu before, you can run this safely.

Then relaunch the OpenClacky installer and retry. If the issue persists, restart your computer, run the command above again, and retry the installer.

Issue 3: A distribution with the provided name already exists — Error code Wsl/Service/RegisterDistro/ERRORALREADYEXISTS

A WSL distribution with the same name already exists, preventing the OpenClacky installer from registering Ubuntu again.

Fix:

Open PowerShell as Administrator and run:

wsl --unregister Ubuntu

⚠️ Warning: This permanently deletes all data inside the distribution. If you previously installed Ubuntu and have important files, back them up first. If you have never installed Ubuntu before, you can run this safely.

Then relaunch the OpenClacky installer and retry. If the issue persists, restart your computer, run the command above again, and retry the installer.

Issue 4: curl: (6) Could not resolve host: oss.1024code.com / [error] Process exited unexpectedly with status: exit code: 127

DNS resolution fails inside WSL, preventing curl from downloading installation resources and causing subsequent steps to abort. Common causes: WSL uses deprecated IPv6 DNS addresses by default, or a VPN / proxy is running on the host machine.

Fix:

Step 1: Disable VPN / proxy and retry

Close any VPN or proxy software on your machine (e.g. Clash, v2ray), then relaunch the OpenClacky installer and retry.

If that resolves the issue, you can skip the steps below.

Step 2: Manually fix DNS (if Step 1 didn't help)

Run the following commands in your WSL terminal:

# Prevent WSL from overwriting resolv.conf on next startup
echo -e "[network]\ngenerateResolvConf = false" | sudo tee /etc/wsl.conf

# Remove the current broken DNS config
sudo rm -f /etc/resolv.conf

# Write working DNS servers (Google 8.8.8.8 and 114.114.114.114)
echo -e "nameserver 8.8.8.8\nnameserver 114.114.114.114" | sudo tee /etc/resolv.conf

Verify DNS is working:

ping -c 3 baidu.com

Once you see replies, relaunch the OpenClacky installer and retry.

Issue 5: Failed to import Ubuntu into WSL2 / Please enable CPU virtualisation in your BIOS/UEFI settings

WSL2 requires CPU virtualisation (Intel VT-x or AMD-V), but it is disabled in your BIOS/UEFI.

Fix:

Step 1: Confirm virtualisation is disabled

Press Ctrl + Shift + Esc to open Task Manager, go to Performance → CPU, and check the Virtualisation field in the bottom-right corner:

• Enabled: Virtualisation is already on — the issue may have another cause. Please contact support.
• Disabled: You need to enable it in BIOS/UEFI.

Step 2: Enter BIOS/UEFI

Restart your computer and press the appropriate key repeatedly as soon as the manufacturer logo appears:

💡 If your PC boots too fast, go to Windows Settings → System → Recovery → Advanced startup → Restart now, then choose Troubleshoot → Advanced options → UEFI Firmware Settings.

Step 3: Enable virtualisation

Inside BIOS, find the virtualisation option (usually under Advanced or CPU Configuration):

• Intel CPU: Enable Intel Virtualization Technology (or Intel VT-x)
• AMD CPU: Enable SVM Mode (or AMD-V)

Save and exit (usually F10). Your PC will reboot automatically.

Step 4: Re-run the installer

Once rebooted, run the OpenClacky install command again.

More troubleshooting entries coming soon. If you're stuck, contact support via the installer.