Troubleshooting

Diagnostics

Always start with:

clustercode doctor

This identifies most common issues and offers to fix them.

Common Issues

Worker shows “offline” in dashboard

Cause: WebSocket connection lost or never established.

Fix:

1. Check the worker is running: clustercode status
2. Verify network access: can you reach the orchestrator URL from this machine?
3. Check firewall rules — outbound WSS (port 443) must be allowed
4. Restart the worker: clustercode worker

”Cannot connect to container runtime”

Cause: Podman (or Docker) is not running or not installed.

Fix (macOS):

podman machine start

Fix (Windows):

podman machine start

Fix (Linux):

systemctl --user start podman.socket

DevBox launch fails with “image not found”

Cause: The DevBox image hasn’t been built on this worker.

Fix:

Build the image from the orchestrator dashboard or ask Nucleus:

“Build the claude-code-terminal image on worker-1"

"Insufficient disk space”

Cause: DevBox images and layers consume significant disk.

Fix:

On Windows, check the Runtime disk line first. Run clustercode doctor. If it reports reclaimable space, much of what’s missing from your drive is space the Podman machine no longer uses but hasn’t given back — run clustercode machine compact before deleting anything. See C: keeps filling up.

Remove stopped DevBoxes you no longer need in the console’s Fleet Cleaner — it lists them with their last activity so you can choose.

To see what’s using space in the container runtime, and to remove images:

# Check current usage
podman system df

# Remove unused images
podman image prune -a

podman image prune -a removes every image that no running or stopped container uses — including images you built yourself and DevBox images the worker will have to build or pull again. Check podman images before running it.

On Windows, pruning frees space inside the machine only; follow it with clustercode machine compact to get that space back on your drive.

C: keeps filling up (Windows)

Symptom: Free space on C: (or whichever drive holds WSL’s data) drops week after week while the worker builds images, and deleting images or DevBoxes doesn’t bring it back. podman system df reports far less than your drive has lost.

Cause: The Podman machine stores everything in one virtual disk file that grows when it needs room and never shrinks on its own. The peak usage of your largest image build becomes a permanent floor on your drive. Deleting files inside the machine — and even running fstrim in it — frees space for the machine to reuse, but returns nothing to Windows.

Fix:

1. Run clustercode doctor. The Runtime disk line shows how much space can be given back (details).
2. Stop clustercode worker, and make sure no DevBox is running — the next step refuses while anything is. Leave the Podman machine itself running: the command needs it up to check and trim, and stops and restarts it for you.
3. Remove stopped DevBoxes you no longer need in the console’s Fleet Cleaner, so their space is free before you compact.
4. Run clustercode machine compact and accept the UAC prompt. It restarts the machine when it’s done, and reports your drive’s free space before and after.
5. Start the worker again.

If the command times out waiting for the disk to be released, another WSL distribution (Ubuntu, Docker Desktop’s) is usually keeping WSL’s VM alive; the message names the ones it found. Run wsl --list --running, stop the others with wsl --terminate <name>, and try again.

If it refuses with Could not confirm that no containers are running, run the check the message names (such as podman machine ssh <machine> podman ps). It lists root’s containers with sudo -n podman ps, so sudo must work inside the machine without a password. With more than one Podman machine, it compacts the default one (or the first listed) and names it first — see which machine.

Two things not to do:

• Don’t run wsl --shutdown to get a compact through. It stops every WSL distribution on the computer, not just the Podman one, and kills whatever is running in them.
• Don’t enable sparse VHDX for the Podman machine. Windows can’t compact a sparse disk this way, and some WSL releases have disabled sparse mode because of a data-corruption risk (details).

The worker slows the regrowth by cleaning up build leftovers inside the machine — see Disk hygiene — but only a compact returns space to Windows. Run it again whenever doctor warns.

Worker shows as disconnected

Cause: A network interruption dropped the worker’s connection to the orchestrator.

The worker reconnects automatically. If it doesn’t recover:

1. Check network connectivity
2. Restart the worker: clustercode worker

Runtime memory too small / “fits ~0 default DevBoxes”

Cause: The container runtime’s VM (macOS/Windows) is only given a small default memory ceiling, or RUNTIME_MEMORY_MB is set below what a default DevBox needs.

Fix:

clustercode onboard --memory 8192

Or run clustercode onboard interactively and pick dedicated-vs-shared sizing — you’ll still be asked to confirm before it applies. See Sizing container runtime memory. On Windows with Podman this rewrites .wslconfig and restarts every WSL distribution on the machine — the guide covers that before you run it. On Windows with Docker, onboard doesn’t apply the change at all; it only tells you whether to edit .wslconfig (WSL2 backend) or Docker Desktop’s settings (Hyper-V backend).

Windows becomes slow or hangs while the worker runs

Cause: The WSL2 VM has grown to its memory ceiling and isn’t giving any of it back. [wsl2] memory= is a ceiling on a balloon that only inflates: with memory reclaim off ([experimental] autoMemoryReclaim=disabled, or a WSL build older than 2.0), the guest’s page cache — everything image pulls and builds have touched — stays charged to Windows until wsl --shutdown. The reserve the CLI subtracted when sizing the runtime is notional in that state, and Windows eventually thrashes into the pagefile.

Reclaim being on — by default or by hand — doesn’t guarantee an escape from this: it’s a request, and some builds accept it and do nothing. On a Windows 10 21H1 machine with WSL 2.7.13, neither gradual nor dropcache returned any of ~9 GB of cache in 16 minutes idle, while dropping the cache by hand returned ~10 GB in 20 seconds. So the ladder below is enable, then verify — and a setting measured inert is graded exactly like no reclaim at all, which lowers the ceiling the CLI thinks this machine can carry.

Diagnose:

clustercode doctor

Look for two lines: Runtime memory: … carrying either memory reclaim is off, so the runtime keeps memory the host may need or memory reclaim is configured but unverified, and the runtime is sized as if it works, and Host memory: … reporting less available than the 4 GiB floor Windows needs — its tail names the reclaim state too (memory reclaim is on but inert on this build, and so on). vmmem (or vmmemWSL) in Task Manager’s Details tab shows the same thing from the other side.

Fix, in order:

1. Turn on memory reclaim — and verify it. Where reclaim is off (disabled, or unset on WSL older than 2.1.3), clustercode onboard offers to turn it on even when the size is already right, and applies it with no resize. It writes [experimental] autoMemoryReclaim=gradual into %UserProfile%\.wslconfig (keeping a .wslconfig.bak copy the first time) and runs wsl --shutdown, which restarts every WSL distribution. It then offers to measure whether the VM really gives memory back. Where reclaim is already on — WSL’s default from 2.1.3 — there’s nothing to write, so go straight to the measurement. Take the offer, or run the measurement yourself once the machine is idle — stop the worker first, because the measurement won’t run while a ClusterCode worker is running:

   clustercode onboard --verify-reclaim

   On WSL older than 2.9.8 in dropCache mode, which is also what a .wslconfig without the key gets, the measurement refuses to run: WSL drops the cache there only after about 10 idle minutes, once per idle period, which a run can’t measure reliably. Go on to steps 2 and 3. See dropCache before WSL 2.9.8. If the answer is no, that’s the end of this step — a configured-but-inert setting is graded as no reclaim at all, the ceiling for this machine drops accordingly, and step 3 is your real fix. If it’s yes, onboard offers to raise the runtime to the larger size a verified host has earned. See Memory reclaim on Windows.
2. Drop the guest’s page cache, for memory you need back now. Reclaim only runs while the VM is idle, and on some older Windows builds it may not trigger at all. The worker already covers this: with Podman on the WSL backend it drops the cache itself whenever Windows falls below 4 GiB available, at most once every 5 minutes and never starting one during a build or commit — see The worker drops the cache itself. Check the worker’s log: a warning that a drop did not raise Windows’ available memory means this step can’t help on your machine, so go to step 3. To free the cache by hand — when the worker isn’t running, or you want the memory back before Windows gets that low — make the same drop the worker makes, interactively from inside the machine:

   podman machine ssh
   sudo sh -c 'sync && echo 1 > /proc/sys/vm/drop_caches'

   echo 1 frees the page cache, which is where this memory is — for the whole WSL VM, which every WSL2 distribution shares. Don’t use echo 3: it also discards the kernel’s directory and inode caches, which buys nothing here. This returns the freed pages to Windows within seconds and does not stop your DevBoxes or any WSL distribution. It’s a stopgap, not a fix: the cache refills as work continues.
3. Lower the ceiling. If reclaim is unavailable, unverified, or measured inert on your build, size the runtime for a VM you assume stays fully inflated. doctor names the value in its own warning — use exactly that:

   clustercode onboard --memory 23552

   (23552 is the figure for a 31.6 GiB host; yours will differ.) With Docker, onboard doesn’t resize anything: lower [wsl2] memory= in .wslconfig (WSL2 backend) or the memory in Docker Desktop’s settings (Hyper-V backend) to the figure doctor names. Docker is always sized as if reclaim does not work, because the CLI can’t measure its VM.
4. wsl --shutdown releases everything immediately. It’s the blunt option — it stops your DevBoxes and every other WSL distribution on the machine — so reach for it only when steps 2 and 3 aren’t enough. Stopping only the Podman distribution may not return the memory: WSL 2 distributions share one VM, which can keep holding it while any of them is still running.

.wslconfig change didn’t take effect

Cause: .wslconfig is encoded as something other than UTF-8 (a common result of Notepad’s legacy “ANSI” save, or PowerShell’s Set-Content), so the CLI refuses to rewrite it rather than risk corrupting your other settings.

Fix: Open %UserProfile%\.wslconfig, re-save it as UTF-8, and re-run clustercode onboard --memory <mb>. Or set the keys by hand and apply them with wsl --shutdown yourself:

[wsl2]
memory=<mb>MB

[experimental]
autoMemoryReclaim=gradual

Note the MB suffix on memory= is mandatory — WSL reads an unsuffixed number as bytes.

Unlike a compact, applying .wslconfig does need wsl --shutdown — but it stops every WSL distribution on the machine, including the Podman machine, so stop running DevBoxes and save work in other distributions first.

WSL issues (Windows)

Cause: WSL2 not installed or not running.

Fix:

wsl --install
# Restart your machine after installation

Verify: wsl --status should show WSL2 as default.

Logs

The worker agent logs to stdout. To capture logs:

clustercode worker 2>&1 | tee ~/.clustercode/worker.log

Still stuck?

• Run clustercode doctor --json and share the output
• Join Discord for community support
• Report a problem or check known issues in the ClusterCode issue tracker