Troubleshooting

Diagnostics

Always start with:

cropscode 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: cropscode 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: cropscode 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

Container launch fails with “image not found”

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

Fix:

Build the image from the orchestrator dashboard or ask CropPilot:

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

Or pull from the registry if available.

”Insufficient disk space”

Cause: Container images and layers consume significant disk.

Fix:

# Remove unused images
podman image prune -a

# Remove stopped containers
podman container prune

# Check current usage
podman system df

Worker heartbeat timeout

Cause: Network interruption lasting more than the heartbeat timeout (30s).

The worker auto-reconnects with exponential backoff. If it doesn’t recover:

1. Check network connectivity
2. Restart the worker: cropscode 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:

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

Still stuck?

• Run cropscode doctor --json and share the output
• Join Discord for community support
• Check GitHub Issues for known issues