Tencent/WeKnora · error

sandbox: docker backend is disabled; enable it in System Set

Error message

sandbox: docker backend is disabled; enable it in System Settings or set WEKNORA_SANDBOX_DOCKER_ENABLED=true

What it means

ErrDockerBackendDisabled is returned when a Docker sandbox config is saved, probed, or resolved while the process has not opted in to the Docker backend. The Docker backend is off by default and requires enabling via the sandbox.docker_enabled system setting or the WEKNORA_SANDBOX_DOCKER_ENABLED environment variable. Handlers map it to 400.

Source

Thrown at internal/sandbox/docker_enabled.go:26

	"sync/atomic"
)

// DockerBackendEnabledEnv is the process-level fallback for the Docker
// sandbox backend. System Settings (sandbox.docker_enabled) override it
// when a row has been pushed by SystemSettingService.
//
// A workspace admin who can save a Docker config can create containers on
// whatever Engine API this process can reach — typically the host's
// docker.sock, which is host root. It is therefore off until a
// SystemAdmin or deployer opts in.
const DockerBackendEnabledEnv = "WEKNORA_SANDBOX_DOCKER_ENABLED"

// DockerBackendEnabledSettingKey is the system_settings registry key.
const DockerBackendEnabledSettingKey = "sandbox.docker_enabled"

// ErrDockerBackendDisabled is returned when a Docker sandbox config is saved,
// probed, or resolved and the process has not opted in.
var ErrDockerBackendDisabled = errors.New(
	"sandbox: docker backend is disabled; enable it in System Settings or set WEKNORA_SANDBOX_DOCKER_ENABLED=true",
)

// dockerBackendEnabledOverride is the runtime-tunable source. Nil means
// "SystemSettingService has not pushed yet"; DockerBackendEnabled then
// reads the env, matching the preload window and tests that only Setenv.
var dockerBackendEnabledOverride atomic.Pointer[bool]

// SetDockerBackendEnabled records the resolved 3-tier value (DB > env >
// false). Called at system_settings preload, Update, Reset, and pubsub reload.
func SetDockerBackendEnabled(enabled bool) {
	v := enabled
	dockerBackendEnabledOverride.Store(&v)
}

// ClearDockerBackendEnabledOverride restores env-only resolution. Tests that
// construct SystemSettingService can otherwise leak a preload push into later
// Setenv-based cases in the same package.

View on GitHub (pinned to 988cbb0330)

Solutions

1. Set WEKNORA_SANDBOX_DOCKER_ENABLED=true in the process environment (or the deployment's env config) and restart, or enable the sandbox.docker_enabled key in System Settings.
2. Verify the env var reaches the actual server process (docker-compose env, k8s ConfigMap/Secret), not just the shell.
3. If the runtime setting was just enabled, retry after the SystemSettingService has loaded (avoid the preload window).
4. If Docker is intentionally disallowed, switch the tenant config to an allowed provider (Cube/E2B) instead.
5. For tests, use t.Setenv("WEKNORA_SANDBOX_DOCKER_ENABLED", "true") rather than relying on settings push.

Example fix

// before: docker config saved without opt-in
cfg := &sandbox.Config{Provider: "docker", Image: "ubuntu:22.04"}
// err -> sandbox.ErrDockerBackendDisabled
// after: enable the backend first (env or system setting)
os.Setenv("WEKNORA_SANDBOX_DOCKER_ENABLED", "true")
// or: SystemSettingService.Set(sandbox.DockerBackendEnabledSettingKey, "true")
if err := sandbox.EnsureDockerBackendAllowed(); err != nil { return err }
_, err := SanitizeSandboxConfig(cfg, nil)

if err := sandbox.EnsureDockerBackendAllowed(); err != nil {
    return err // surfaces the exact enablement instructions
}
// only then save/resolve a docker provider config

func dockerBackendAvailable() bool {
    return os.Getenv("WEKNORA_SANDBOX_DOCKER_ENABLED") == "true"
}

_, err := SanitizeSandboxConfig(cfg, nil)
if err != nil {
    if errors.Is(err, sandbox.ErrDockerBackendDisabled) {
        return fmt.Errorf("enable docker backend via %s setting or env, then retry",
            sandbox.DockerBackendEnabledSettingKey)
    }
    return err
}

When it happens

Trigger: Saving a tenant sandbox config with provider=docker, probing/resolving it, or calling EnsureDockerBackendAllowed when neither the system setting sandbox.docker_enabled is true nor WEKNORA_SANDBOX_DOCKER_ENABLED=true is set; also during the preload window before SystemSettingService has pushed the setting (nil override reads only env).

Common situations: Fresh deployment where the Docker opt-in env var was never set; operators enable the setting at runtime but a request arrives before the settings service pushes the override; switching a tenant's sandbox provider to docker in a shared environment that deliberately disallows Docker.

Related errors

• sandbox: docker client requires a config
• sandbox: docker backend requires an image
• sandbox: config is missing required fields
• daemon returned no container state
• e2b remote client config is required

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