Template Troubleshooting

Common template-related issues and their solutions.

Template creation fails

Image pull timeout

Symptom: Template creation fails during image download.

Fix:

• Check network connectivity to the registry
• For China users, use cube-sandbox-cn.tencentcloudcr.com registry
• For international users, use cube-sandbox-int.tencentcloudcr.com registry

Insufficient disk space

Symptom: Template creation fails with disk space errors.

Fix: Template creation requires significant disk space:

• Image download and extraction
• Snapshot creation
• Distribution to nodes

Ensure at least 20-30 GB free on the data disk.

Template build hangs

Symptom: Template creation appears to hang.

Fix:

1. Check build progress:

   cubemastercli tpl watch --job-id <job_id>

2. Check CubeMaster logs:

   sudo tail -200 /data/log/CubeMaster/cubemaster-req.log

3. If stuck for more than 30 minutes, cancel and retry:

   cubemastercli tpl cancel --job-id <job_id>

Template distribution issues

Template not available on specific node

Symptom: Sandbox creation fails on certain nodes with template not found.

Fix: Redistribute the template:

cubemastercli tpl redo --template-id <template-id> --node <node-ip>

Template version mismatch

Symptom: Sandbox creation fails after CubeSandbox upgrade.

Fix: Rebuild the template after upgrading CubeSandbox:

cubemastercli tpl create-from-image \
  --image <your-image> \
  --writable-layer-size 1G \
  --expose-port 49999 \
  --probe 49999

Template inspection

List all templates

cubemastercli tpl list

View template details

cubemastercli tpl info --template-id <template-id>

Preview template requests

Use the template inspection tool to preview API requests. See Template Inspection & Request Preview.