Tencent/WeKnora · error

sandbox: config is missing required fields

Error message

sandbox: config is missing required fields

What it means

ErrSandboxConfigIncomplete marks a named sandbox config that cannot build a working client because required fields for its provider (Cube, E2B, Docker, etc.) are empty. MissingRequiredFields lists the offending fields using the JSON key names shown in the API/settings form, so the message can be surfaced directly to users. Callers map it onto HTTP 400.

Source

Thrown at internal/sandbox/config_required.go:29

//   - Values the SDK resolves by itself. go-e2b defaults both the API base URL
//     and the sandbox domain when they are left empty, so demanding them would
//     force operators to spell out constants they cannot verify.
//
// Everything else is required precisely because its absence fails late and
// obscurely: a missing Cube proxy URL or sandbox domain still creates a sandbox
// and only breaks when envd traffic is routed, which reads as a provider outage
// rather than a typo in the form.
package sandbox

import (
	"errors"
	"fmt"
	"strings"
)

// ErrSandboxConfigIncomplete marks a named config that cannot build a working
// client because required fields are empty. Callers map it onto 400.
var ErrSandboxConfigIncomplete = errors.New("sandbox: config is missing required fields")

// MissingRequiredFields lists the fields cfg fails to supply for its own
// provider, named after the JSON keys the API and the settings form use so the
// message can be surfaced without translation. Disabled holds no
// backend-specific values; Docker must explicitly name its image.
func MissingRequiredFields(cfg *Config) []string {
	if cfg == nil {
		return nil
	}
	var missing []string
	require := func(field, value string) {
		if strings.TrimSpace(value) == "" {
			missing = append(missing, field)
		}
	}
	switch cfg.Type {
	case SandboxTypeCube:
		require("api_url", cfg.CubeAPIURL)

View on GitHub (pinned to 988cbb0330)

Solutions

1. Open the sandbox settings for the tenant and fill every field listed in the error message (e.g. proxy_url, image).
2. Call sandbox.MissingRequiredFields(cfg) before saving/resolving to get the exact missing JSON keys and show them in the UI.
3. If the field is intentionally unset, switch the config's provider to one whose required fields are satisfied, or disable the sandbox.
4. Verify via tests that SanitizeSandboxConfig/Resolve paths return ErrSandboxConfigIncomplete early with the field name in the message.

Example fix

// before: saving incomplete cube config
incoming := &sandbox.Config{Provider: "cube"} // proxy_url empty
_, err := SanitizeSandboxConfig(incoming, nil) // -> ErrSandboxConfigIncomplete (proxy_url)
// after: validate and surface missing fields first
if missing := sandbox.MissingRequiredFields(incoming); len(missing) > 0 {
    return fmt.Errorf("sandbox config missing: %s", strings.Join(missing, ", "))
}
_, err := SanitizeSandboxConfig(incoming, nil)

if missing := sandbox.MissingRequiredFields(cfg); len(missing) > 0 {
    return fmt.Errorf("%w: missing %s",
        sandbox.ErrSandboxConfigIncomplete, strings.Join(missing, ", "))
}

func sandboxConfigComplete(cfg *sandbox.Config) bool {
    return len(sandbox.MissingRequiredFields(cfg)) == 0
}

if err != nil {
    if errors.Is(err, sandbox.ErrSandboxConfigIncomplete) {
        // 400 with the field names from the message
        http.Error(w, err.Error(), http.StatusBadRequest)
        return
    }
}

When it happens

Trigger: Saving, sanitizing, probing, or resolving a tenant sandbox config where a mandatory provider field is blank — e.g. a Cube config missing proxy_url, an E2B config missing its API key, or a Docker config without an image name.

Common situations: Admin partially fills the sandbox settings form and saves; env-driven config missing required variables; config imported/ copied between tenants with provider-specific fields dropped; Docker image name never set after switching provider to docker.

Understand the failure class

Background: Schema validation failed / invalid input schema: payload rejected because its shape doesn't match the expected schema — this error's family across 28 libraries.

Related errors

• ErrNamedSandboxBackendUnsupported
• sandbox: docker backend is disabled; enable it in System Set
• sandbox: docker client requires a config
• sandbox: docker backend requires an image
• e2b remote client config is required

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