sandbox: docker network mode %q is not allowed; use "bridge"

Error message

sandbox: docker network mode %q is not allowed; use "bridge" or "none"

What it means

ValidateDockerNetworkMode restricts the docker network mode of sandbox containers to exactly "bridge" or "none" (case-insensitive). Any other mode — host, container:<id>, custom networks — is rejected to prevent sandboxed workloads from escaping isolation or reaching networks they should not see.

Source

Thrown at internal/sandbox/docker_engine.go:328

//
// host and container: modes share another namespace outright, which would put
// sandbox code on the WeKnora host's or a sibling container's network. A
// user-defined network name is refused for the weaker but equally real version
// of the same problem: the usual deployment reaches its daemon through the
// mounted docker.sock, so naming the deployment's own compose network would
// place a sandbox on the same L3 network as Postgres and Redis. Only the
// operator can judge what a given named network exposes, and this value is set
// per workspace config, so it is not theirs to choose.
func ValidateDockerNetworkMode(mode string) error {
	trimmed := strings.TrimSpace(mode)
	if trimmed == "" {
		return nil
	}
	switch strings.ToLower(trimmed) {
	case "bridge", "none":
		return nil
	}
	return fmt.Errorf(
		"sandbox: docker network mode %q is not allowed; use \"bridge\" or \"none\"",
		mode)
}

// dockerErrorKind classifies an Engine API error. The moby client tags its
// errors with containerd's errdefs, which is a far more reliable signal than
// the message text.
func dockerErrorKind(op string, err error) RemoteErrorKind {
	switch {
	case err == nil:
		return ""
	case errors.Is(err, context.DeadlineExceeded), cerrdefs.IsDeadlineExceeded(err):
		return RemoteErrorKindTimeout
	case cerrdefs.IsNotFound(err):
		// A missing image on create is a bad template, not a vanished sandbox:
		// classifying it as NotFound would tell the lifecycle it may rebind.
		if op == "Create" {
			return RemoteErrorKindInvalidRequest

View on GitHub (pinned to 988cbb0330)

Solutions

Change the network mode to "none" for maximum isolation (add explicit DNS/DNS servers, e.g. cube DNS settings, if network access is needed)
Use "bridge" when the sandbox needs default outbound connectivity through Docker's bridge
Remove any custom network names or container: modes — they are not supported by policy
Note the comparison is case-insensitive; "Bridge" or "NONE" are accepted

Example fix

// before
NetworkMode: "host"
// after
NetworkMode: "none" // or "bridge" if outbound access is required

Defensive patterns

Strategy: validation

Validate before calling

mode := strings.ToLower(strings.TrimSpace(cfg.Docker.NetworkMode))
if mode != "" && mode != "bridge" && mode != "none" {
    return fmt.Errorf("network mode %q rejected; use bridge or none", cfg.Docker.NetworkMode)
}

Type guard

func isAllowedNetworkMode(mode string) bool {
    switch strings.ToLower(strings.TrimSpace(mode)) { case "", "bridge", "none": return true }
    return false
}

Try / catch

if err := sandbox.ValidateDockerNetworkMode(cfg.Docker.NetworkMode); err != nil {
    if strings.Contains(err.Error(), "not allowed") { cfg.Docker.NetworkMode = "none" }
    return err
}

Prevention

Only ever emit "bridge" or "none" from config generation code
Do not port --network host/container habits into sandbox configs — host networking defeats isolation
Add a config lint test asserting every shipped profile passes ValidateDockerNetworkMode

When it happens

Trigger: Setting the sandbox docker network mode config field to "host", "container:abc123", a custom network name, or any value other than bridge/none, then calling ResolveEffectiveConfig, dockerSettingsFromConfig, or TestValidateDockerNetworkMode.

Common situations: Copying docker run --network host habits into sandbox config; pointing containers at an internal registry network by name; defaulting to host networking for performance reasons.

Related errors

AI-assisted analysis of Tencent/WeKnora@988cbb0330 (2026-09-02). Data as JSON: /api/errors/4fef627e558b2bc8. Report an issue: GitHub.