Tencent/WeKnora · error

sandbox: docker client requires a config

Error message

sandbox: docker client requires a config

What it means

dockerSettingsFromConfig projects the workspace Config into Docker runtime settings and refuses to build a Docker remote client when it is handed a nil *Config. The library requires an explicit configuration object because every sandbox backend derives its runtime parameters (image, CPU, memory, pids limits, network policy) from it. A nil config is treated as a programming/caller error rather than something a default can be inferred for.

Source

Thrown at internal/sandbox/docker_remote_client.go:154

// newDockerRemoteClientWithAPI is the seam unit tests use: it takes any
// dockerEngineAPI, including an in-memory fake.
func newDockerRemoteClientWithAPI(
	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,

View on GitHub (pinned to 988cbb0330)

Solutions

1. Ensure the *Config passed to NewDockerRemoteClient/NewDockerRemoteClientForCheck is non-nil before calling
2. Check the config-loading function for code paths that can return (nil, nil) and fix them
3. Fall back to a default Config value when no workspace config is present

Example fix

// before
client, err := sandbox.NewDockerRemoteClient(nil)
// after
if cfg == nil {
    return nil, fmt.Errorf("no sandbox config: %w", err)
}
client, err := sandbox.NewDockerRemoteClient(cfg)

if cfg == nil {
    return fmt.Errorf("docker sandbox requires config: docker client requires a config")
}
if strings.TrimSpace(cfg.DockerImage) == "" {
    return errors.New("docker sandbox requires an image")
}

func hasDockerConfig(cfg *sandbox.Config) bool { return cfg != nil }

When it happens

Trigger: Calling NewDockerRemoteClient, NewDockerRemoteClientForCheck (or the test helpers newTestDockerClient) with a nil *Config argument, typically because a Config struct was conditionally populated or a nil pointer was passed through from an upstream loader.

Common situations: Config loading failed silently earlier and returned nil; a caller short-circuits an optional-config pattern and forwards nil; refactors changed Config from value to pointer semantics and existing call sites now pass nil.

Related errors

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

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