# Troubleshooting CubeSandbox Configuration Errors: A Complete Guide

> Resolve CubeSandbox configuration errors with this expert guide. Learn to fix invalid CLI flags, socket path mismatches, and missing kernel modules for seamless operation.

- Repository: [Tencent Cloud/CubeSandbox](https://github.com/TencentCloud/CubeSandbox)
- Tags: how-to-guide
- Published: 2026-07-13

---

**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`](https://github.com/TencentCloud/CubeSandbox/blob/main/network-agent/docs/CONFIGURATION.md), the agent validates these inputs through `ValidateConfig()` in [`internal/config/config.go`](https://github.com/TencentCloud/CubeSandbox/blob/main/internal/config/config.go).

### CLI Flag Validation

The entry point at [`cmd/network-agent/main.go`](https://github.com/TencentCloud/CubeSandbox/blob/main/cmd/network-agent/main.go) parses these critical flags:

| Flag | Default | Common Error | Source Reference |
|------|---------|--------------|------------------|
| `--eth-name` | *(required)* | `Error: network interface "eth0" not found` | Lines 27-42 of [`CONFIGURATION.md`](https://github.com/TencentCloud/CubeSandbox/blob/main/CONFIGURATION.md) |
| `--cidr` | `192.168.0.0/18` | `invalid CIDR: "192.168.0.0"` | Lines 35-38 |
| `--listen` | `unix:///tmp/cube/network-agent.sock` | `bind: address already in use` | Lines 21-24 |
| `--state-dir` | `/usr/local/services/cubetoolbox/network-agent/state` | `state directory not writable` | Lines 50-53 |

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:

```toml
[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