{"record":{"id":"08f4203e8e53a35a","repo":"Tencent/WeKnora","slug":"sandbox-docker-backend-is-disabled-enable-it-in","errorCode":null,"errorMessage":"sandbox: docker backend is disabled; enable it in System Settings or set WEKNORA_SANDBOX_DOCKER_ENABLED=true","messagePattern":"sandbox: docker backend is disabled; enable it in System Settings or set WEKNORA_SANDBOX_DOCKER_ENABLED=true","errorType":"error_code","errorClass":null,"httpStatus":null,"severity":"error","filePath":"internal/sandbox/docker_enabled.go","lineNumber":26,"sourceCode":"\t\"sync/atomic\"\n)\n\n// DockerBackendEnabledEnv is the process-level fallback for the Docker\n// sandbox backend. System Settings (sandbox.docker_enabled) override it\n// when a row has been pushed by SystemSettingService.\n//\n// A workspace admin who can save a Docker config can create containers on\n// whatever Engine API this process can reach — typically the host's\n// docker.sock, which is host root. It is therefore off until a\n// SystemAdmin or deployer opts in.\nconst DockerBackendEnabledEnv = \"WEKNORA_SANDBOX_DOCKER_ENABLED\"\n\n// DockerBackendEnabledSettingKey is the system_settings registry key.\nconst DockerBackendEnabledSettingKey = \"sandbox.docker_enabled\"\n\n// ErrDockerBackendDisabled is returned when a Docker sandbox config is saved,\n// probed, or resolved and the process has not opted in.\nvar ErrDockerBackendDisabled = errors.New(\n\t\"sandbox: docker backend is disabled; enable it in System Settings or set WEKNORA_SANDBOX_DOCKER_ENABLED=true\",\n)\n\n// dockerBackendEnabledOverride is the runtime-tunable source. Nil means\n// \"SystemSettingService has not pushed yet\"; DockerBackendEnabled then\n// reads the env, matching the preload window and tests that only Setenv.\nvar dockerBackendEnabledOverride atomic.Pointer[bool]\n\n// SetDockerBackendEnabled records the resolved 3-tier value (DB > env >\n// false). Called at system_settings preload, Update, Reset, and pubsub reload.\nfunc SetDockerBackendEnabled(enabled bool) {\n\tv := enabled\n\tdockerBackendEnabledOverride.Store(&v)\n}\n\n// ClearDockerBackendEnabledOverride restores env-only resolution. Tests that\n// construct SystemSettingService can otherwise leak a preload push into later\n// Setenv-based cases in the same package.","sourceCodeStart":8,"sourceCodeEnd":44,"githubUrl":"https://github.com/Tencent/WeKnora/blob/988cbb03305e055d8ebb7d46d9ac6cc0803cd074/internal/sandbox/docker_enabled.go#L8-L44","documentation":"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.","triggerScenarios":"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).","commonSituations":"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.","solutions":["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.","Verify the env var reaches the actual server process (docker-compose env, k8s ConfigMap/Secret), not just the shell.","If the runtime setting was just enabled, retry after the SystemSettingService has loaded (avoid the preload window).","If Docker is intentionally disallowed, switch the tenant config to an allowed provider (Cube/E2B) instead.","For tests, use t.Setenv(\"WEKNORA_SANDBOX_DOCKER_ENABLED\", \"true\") rather than relying on settings push."],"exampleFix":"// before: docker config saved without opt-in\ncfg := &sandbox.Config{Provider: \"docker\", Image: \"ubuntu:22.04\"}\n// err -> sandbox.ErrDockerBackendDisabled\n// after: enable the backend first (env or system setting)\nos.Setenv(\"WEKNORA_SANDBOX_DOCKER_ENABLED\", \"true\")\n// or: SystemSettingService.Set(sandbox.DockerBackendEnabledSettingKey, \"true\")\nif err := sandbox.EnsureDockerBackendAllowed(); err != nil { return err }\n_, err := SanitizeSandboxConfig(cfg, nil)","handlingStrategy":"validation","validationCode":"if err := sandbox.EnsureDockerBackendAllowed(); err != nil {\n    return err // surfaces the exact enablement instructions\n}\n// only then save/resolve a docker provider config","typeGuard":"func dockerBackendAvailable() bool {\n    return os.Getenv(\"WEKNORA_SANDBOX_DOCKER_ENABLED\") == \"true\"\n}","tryCatchPattern":"_, err := SanitizeSandboxConfig(cfg, nil)\nif err != nil {\n    if errors.Is(err, sandbox.ErrDockerBackendDisabled) {\n        return fmt.Errorf(\"enable docker backend via %s setting or env, then retry\",\n            sandbox.DockerBackendEnabledSettingKey)\n    }\n    return err\n}","preventionTips":["Set WEKNORA_SANDBOX_DOCKER_ENABLED=true in deployment env when Docker sandboxes are wanted.","Enable the sandbox.docker_enabled System Settings key and wait for the settings service push.","Hide/disable the docker provider option in the UI when the backend is off.","In tests use t.Setenv to opt in deterministically."],"tags":["sandbox","docker","feature-flag","config"],"backgroundTag":"feature-disabled-by-config","analyzedSha":"988cbb03305e055d8ebb7d46d9ac6cc0803cd074","analyzedAt":"2026-09-02T14:41:08.344Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-08T10:18:20.063Z"}