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:

# Remove unused images
podman image prune -a

# Remove stopped DevBoxes
podman container prune

# Check current usage
podman system df

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

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