-
-
Notifications
You must be signed in to change notification settings - Fork 178
v2 Troubleshooting
Common problems and how to deal with them. If none of this helps, please open an issue — including your app version (shown in the title bar) and what you were doing. Error messages in the app now say what failed and what to do about it, so please paste them verbatim.
macOS-specific problems (Gatekeeper, vmctl, VMs that stop at once, Finder and disks) are on the macOS page.
The app shows no distros
Check WSL itself works first: run wsl --list --verbose in PowerShell. If that's empty or errors, the problem is with your WSL installation, not the app. wsl --install sets it up on a clean machine.
"WSL 2 needs the Virtual Machine Platform Windows feature" Turn on Virtual Machine Platform under Windows features and restart the computer.
"WSL could not start its virtual machine" (CreateInstance/E_FAIL)
Usually low disk space or a stale WSL session: free some space, run wsl --shutdown, try again.
A distro won't stop Something still has a session open — close terminals and editors (VS Code in particular) attached to it. Settings → Stop WSL shuts down the entire subsystem, which always works but stops everything.
The list flickers or briefly empties It shouldn't any more — one failed background refresh keeps the previous list. If it does, please report it with the status-bar message.
Several of the heavier operations — copying, moving, exporting, packaging, sandboxes and especially AI Workspace installs — need substantial free space, and failures under low disk conditions can be confusing (containers exiting immediately, installs stopping midway, WSL becoming unresponsive). Copy needs as much free space again as the instance; a sandbox about 3 GB.
If something large fails for no obvious reason, check free space on C: first. WSL virtual disks don't shrink automatically when you delete files inside them — use Cleanup in the distro row (it checks free space first) or, by hand:
wsl --shutdown
Optimize-VHD -Path "C:\path\to\ext4.vhdx" -Mode Full # needs an elevated shell + Hyper-V moduleCommands hang or fail with odd errors
Orphaned wsl.exe / wslhost.exe processes can wedge WSL. A clean restart usually fixes it:
wsl --shutdownThen reopen the app. This is safe — it just stops running distros.
A setting says "Deprecated since WSL 2.4.5" or "requires WSL …"
The app gates features on the installed WSL version: .wsl packages need the Store build of WSL, --set-default-user needs 2.5+, native move needs a current WSL. Update WSL from Settings → Global configuration.
On a current WSL, Move runs wsl --manage --move — a single supported operation where the distro is never unregistered. On older versions it falls back to export → unregister → import; don't close the app during that, and don't delete the export file until the instance is back. If a move fails complaining the export is too small, the export genuinely didn't produce a usable file — usually low disk space or a permissions problem on the target path.
"Device Flow must be explicitly enabled for this App" when sharing GitHub's own message: the project's OAuth app hasn't had device flow switched on yet. Nothing to fix on your side — report it, and add the snippet as a manual PR on bostrot/wsl-scripts meanwhile.
Community snippets could not be downloaded Check your internet connection; the list comes from GitHub.
"AI Chat needs your own API key" / "Sign in with your Claude account" Pick and configure a provider under Settings → Bring Your Own AI Key — see AI Assistant → Choosing a provider. Use Test connection to confirm the credentials before chatting.
"Sign in with Claude needs a client ID" That provider isn't enabled in your build. Use an OpenAI-compatible key instead.
The assistant keeps running after I pressed Cancel Cancel ends the agent loop and the auto-continue; if a tool call was mid-flight it finishes, then nothing else runs. If you see further tool calls after that, please report it.
AI Workspace — see the AI Workspace troubleshooting section for "not installed" detection issues, dashboards returning an empty response, and the macOS VM not answering over SSH.
My MCP client can't connect
Confirm the server toggle is on, and that your client sends Authorization: Bearer <token> with the exact token shown in Settings. Regenerating the token invalidates old clients. Stdio-only clients need the mcp-remote bridge — see Connecting a client.
"Connect Claude Desktop" says Claude Desktop was not found
The quick-connect writes Claude Desktop's config file; if the app isn't installed in its default location, add the entry by hand. It also needs Node.js for npx.
Port already in use
Something else is on 59133. Stop that process; the app leaves the server disabled rather than failing loudly if the port can't be bound.
See Remote WSL troubleshooting.
The in-app bug report button (the small icon in the title bar) pre-fills useful context. Otherwise, please include:
- App version (title bar, e.g.
v1.12.0) and platform (Windows / macOS) - Whether you installed from the Microsoft Store, a GitHub release, winget/Scoop/Chocolatey, or the macOS DMG
- Output of
wsl --list --verboseandwsl --version(Windows) - What you did, what you expected, what happened