Deployment Troubleshooting

Common deployment issues and their solutions.

Installation fails

Docker not running

Symptom: Installation script exits with Docker-related errors.

Fix:

sudo systemctl start docker
sudo systemctl enable docker

Insufficient disk space

Symptom: Template creation or sandbox creation fails with disk errors.

Fix: Check available disk space:

df -h /data

Ensure at least 50 GB free. If using XFS, verify reflink support:

xfs_info /data | grep reflink

KVM not available

Symptom: Sandbox creation fails with KVM-related errors.

Fix: Verify KVM is available:

ls -la /dev/kvm

If not available, use PVM deployment instead. See Quick Start.

Service startup failures

Cubelet fails to start

Check logs:

sudo journalctl -u cube-sandbox-cubelet.service -n 200

Common causes:

• Network agent not ready: restart network-agent first
• Storage path not mounted: verify /data/cubelet exists and is XFS
• Config syntax error: validate config.toml

CubeProxy fails to start

Check logs:

sudo journalctl -u cube-sandbox-cube-proxy.service -n 200

Common causes:

• Redis not ready: check cube-sandbox-redis.service
• Port conflict: another process using port 80 or 443

Sandbox creation fails

Template not ready

Symptom: Sandbox creation returns template-related errors.

Fix: Check template status:

cubemastercli tpl list

Wait for template status to become READY.

Network timeout

Symptom: Sandbox creation times out.

Fix: Check if sandbox CIDR overlaps with host LAN. See CIDR Conflict Troubleshooting.