Tencent/WeKnora · error · ErrSandboxConfigIncomplete

sandbox: config is missing required fields: %s backend requi

Error message

sandbox: config is missing required fields: %s backend requires %s

What it means

RequireCompleteConfig validates that a sandbox config has all required fields for its selected backend type. It returns ErrSandboxConfigIncomplete wrapped with the backend provider name and the comma-separated list of missing fields, so callers can errors.Is() against the sentinel while still seeing which keys to set.

Source

Thrown at internal/sandbox/config_required.go:72

	case SandboxTypeDocker:
		require("image", cfg.DockerImage)
	}
	return missing
}

// RequireCompleteConfig is the error form of MissingRequiredFields, shared by
// the save path and the resolve path so both reject the same configs with the
// same wording.
func RequireCompleteConfig(cfg *Config) error {
	missing := MissingRequiredFields(cfg)
	if len(missing) == 0 {
		return nil
	}
	provider := ""
	if cfg != nil {
		provider = string(cfg.Type)
	}
	return fmt.Errorf(
		"%w: %s backend requires %s",
		ErrSandboxConfigIncomplete, provider, strings.Join(missing, ", "),
	)
}

View on GitHub (pinned to 988cbb0330)

Solutions

1. Read the error's field list and set each named field on the sandbox config
2. Run RequireCompleteConfig (or ResolveEffectiveConfig) early at startup to fail fast with the full missing-field list
3. Ensure the config Type matches the fields you populated — a docker-typed config needs docker settings, not cube ones
4. Check environment variables/config file for empty-string values that parse as missing

Example fix

// before
cfg := &sandbox.Config{Type: sandbox.TypeDocker} // missing host
// after
cfg := &sandbox.Config{Type: sandbox.TypeDocker, Docker: sandbox.DockerSettings{Host: "unix:///var/run/docker.sock", Image: "sandbox:latest"}}
if err := sandbox.RequireCompleteConfig(cfg); err != nil { log.Fatal(err) }

if err := sandbox.RequireCompleteConfig(cfg); err != nil {
    if errors.Is(err, sandbox.ErrSandboxConfigIncomplete) {
        log.Fatalf("sandbox config incomplete: %v", err) // message lists missing fields
    }
    return err
}

func hasRequiredDockerFields(cfg *sandbox.Config) bool {
    return cfg != nil && cfg.Type == sandbox.TypeDocker && cfg.Docker.Host != "" && cfg.Docker.Image != ""
}

cfg, err := sandbox.ResolveEffectiveConfig(ctx, raw)
if err != nil && errors.Is(err, sandbox.ErrSandboxConfigIncomplete) {
    // parse the 'backend requires ...' tail to surface missing fields to the user
}

When it happens

Trigger: Calling ResolveEffectiveConfig with a SandboxConfig whose Type selects a backend (e.g. docker, cube) but which omits that backend's mandatory settings (e.g. docker host, image, TLS cert dir). The missing fields are enumerated in the error message.

Common situations: Partial configs assembled from env vars where only some keys are set; switching sandbox type without migrating the type-specific fields; a defaults merge leaving empty strings that count as missing.

Related errors

• invalid sandbox type
• timeout cannot be negative
• memory limit cannot be negative
• CPU limit cannot be negative
• sandbox: docker host %q must include a scheme (unix:// or tc

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