Troubleshooting CubeSandbox Configuration Errors: A Complete Guide

Most CubeSandbox configuration errors stem from invalid CLI flags in the Network Agent, mismatched socket paths between Cubelet and the agent, or missing kernel modules like vhost_net.

CubeSandbox is a container-native sandbox platform developed by TencentCloud that orchestrates micro-VMs through tightly-coupled components including Cubelet, Network Agent, and CubeShim. When these services fail to start or communicate, the root cause typically lies in misconfigured TOML files, incorrect file permissions, or incompatible host kernel settings. This guide walks through the exact source code locations and validation logic you need to diagnose and fix these issues.

Network Agent Configuration Errors

The Network Agent processes configuration in three cascading layers: CLI flags override Cubelet TOML settings, which in turn override hardcoded defaults. According to the configuration documentation in network-agent/docs/CONFIGURATION.md, the agent validates these inputs through ValidateConfig() in internal/config/config.go.

CLI Flag Validation

The entry point at cmd/network-agent/main.go parses these critical flags:

If you see "missing required field" errors, verify that required parameters like --eth-name are explicitly set and that the interface exists on the host.

Cubelet TOML Overrides

When using --cubelet-config=/etc/cubelet/config.toml, the agent reads the [network] section. Ensure your TOML includes the mandatory [network] and [network.mvm] blocks:

[network]
cidr = "192.168.0.0/16"

[network.mvm]
inner_ip = "169.254.68.6"
mac_addr = "20:90:6f:fc:fc:fc"
gw_dest_ip = "169.254.68.5"
gw_mac_addr = "20:90:6f:cf:cf:cf"
mask