Tencent/WeKnora · error

sandbox: docker backend requires an image

Error message

sandbox: docker backend requires an image

What it means

After applying defaults, dockerSettingsFromConfig requires cfg.DockerImage to name a container image; the Docker backend cannot create a sandbox without one, so an empty (or whitespace-only) DockerImage is rejected. This is a fail-fast validation so misconfiguration surfaces at client construction rather than at sandbox Create time.

Source

Thrown at internal/sandbox/docker_remote_client.go:158

	api dockerEngineAPI,
	settings dockerRuntimeSettings,
) *DockerRemoteClient {
	adapter := &DockerRemoteClient{api: api, settings: settings}
	if settings.IdleTTL > 0 {
		adapter.sweeper = newDockerIdleSweeper(adapter, settings.IdleTTL)
	}
	return adapter
}

// dockerSettingsFromConfig projects Config, applying the built-in defaults for
// every value the workspace config leaves unset.
func dockerSettingsFromConfig(cfg *Config) (dockerRuntimeSettings, error) {
	if cfg == nil {
		return dockerRuntimeSettings{}, errors.New("sandbox: docker client requires a config")
	}
	image := strings.TrimSpace(cfg.DockerImage)
	if image == "" {
		return dockerRuntimeSettings{}, errors.New("sandbox: docker backend requires an image")
	}
	settings := dockerRuntimeSettings{
		Image:       image,
		CPULimit:    cfg.DockerCPULimit,
		MemoryBytes: cfg.DockerMemoryBytes,
		PidsLimit:   cfg.DockerPidsLimit,
		NetworkMode: strings.TrimSpace(cfg.DockerNetworkMode),
		Runtime:     strings.TrimSpace(cfg.DockerRuntime),
		IdleTTL:     cfg.DockerIdleTTL,
		HTTPTimeout: cfg.DockerHTTPTimeout,
		Endpoint: dockerEndpoint{
			Host:         strings.TrimSpace(cfg.DockerHost),
			TLSCertPath:  strings.TrimSpace(cfg.DockerTLSCertPath),
			AllowPrivate: cfg.AllowPrivateEndpoints,
			Timeout:      cfg.DockerHTTPTimeout,
		},
	}
	if settings.CPULimit <= 0 {

View on GitHub (pinned to 988cbb0330)

Solutions

1. Set cfg.DockerImage to a valid image reference (e.g. "ubuntu:24.04") before constructing the client
2. Check the workspace config file / env vars actually populate DockerImage (trailing whitespace is trimmed, so " " still fails)
3. Use the library's default config constructor if one exists so the built-in default image is applied

Example fix

// before
cfg := &sandbox.Config{DockerCPULimit: 2}
// after
cfg := &sandbox.Config{DockerImage: "ubuntu:24.04", DockerCPULimit: 2}

if strings.TrimSpace(cfg.DockerImage) == "" {
    return errors.New("docker sandbox requires an image before client construction")
}

When it happens

Trigger: Constructing a Docker remote client via NewDockerRemoteClient or NewDockerRemoteClientForCheck while cfg.DockerImage is unset or contains only whitespace.

Common situations: Workspace config file omits the docker image key; environment variable substitution resolves to empty; a config struct is built programmatically and only limits are set; TestDockerSettingsRequireImage exercises exactly this path.

Related errors

• sandbox: docker client requires a config
• sandbox: docker backend is disabled; enable it in System Set
• daemon returned no container state
• e2b remote client config is required
• E2BAPIKey is required for the E2B backend

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