Tencent/WeKnora · error

sandbox: unsupported docker host scheme %q

Error message

sandbox: unsupported docker host scheme %q

What it means

ValidateDockerHost only supports unix, tcp, http, and https schemes for the docker host. Any other scheme (e.g. npipe://, ssh://, fd://) reaches the default branch and is rejected, because the sandbox guard only knows how to validate Unix sockets and HTTP-reachable daemons.

Source

Thrown at internal/sandbox/docker_engine.go:282

	scheme, address, found := strings.Cut(trimmed, "://")
	if !found {
		return fmt.Errorf(
			"sandbox: docker host %q must include a scheme (unix:// or tcp://)", host)
	}
	switch strings.ToLower(scheme) {
	case "unix":
		if !strings.HasPrefix(address, "/") {
			return fmt.Errorf("sandbox: docker unix socket path %q must be absolute", address)
		}
		return nil
	case "tcp", "http", "https":
		// The guard speaks HTTP; the daemon's TCP endpoint is an HTTP
		// endpoint, so the check is the same one every other backend gets.
		return ValidateOutboundURLWithPolicy(
			"http://"+address, OutboundURLPolicy{AllowPrivate: allowPrivate},
		)
	default:
		return fmt.Errorf("sandbox: unsupported docker host scheme %q", scheme)
	}
}

// ValidateDockerRemoteTLS requires client certificates for a TCP daemon.
// A remote Engine API that accepts container creation is a root shell on
// that host; plaintext tcp://2375 is not an acceptable way to reach it.
// Unix sockets are local to the WeKnora process and do not use TLS.
func ValidateDockerRemoteTLS(host, tlsCertPath string) error {
	trimmed := strings.TrimSpace(host)
	if trimmed == "" {
		return nil
	}
	scheme, _, found := strings.Cut(trimmed, "://")
	if !found {
		return nil
	}
	switch strings.ToLower(scheme) {
	case "tcp", "http", "https":

View on GitHub (pinned to 988cbb0330)

Solutions

1. Replace the scheme with tcp://host:port or https:// and run the daemon's TCP endpoint (with TLS, see ValidateDockerRemoteTLS)
2. For Windows named pipes, expose the daemon on a TCP port instead, or run the sandbox guard on a host that can reach unix:///var/run/docker.sock
3. Drop ssh:// in favor of an HTTPS-secured remote Engine API endpoint
4. Check the lowercase scheme — validation lowercases the scheme, so "TCP://" is fine but typos like "tcp ://" are not

Example fix

// before
Host: "ssh://user@build-host"
// after
Host: "tcp://build-host:2376" // with TLS cert dir configured

scheme, _, _ := strings.Cut(strings.TrimSpace(cfg.Docker.Host), "://")
switch strings.ToLower(scheme) {
case "", "unix", "tcp", "http", "https":
default:
    return fmt.Errorf("unsupported docker scheme %q; use tcp:// or https://", scheme)
}

func schemeSupported(host string) bool {
    s, _, ok := strings.Cut(strings.TrimSpace(host), "://")
    if !ok { return true }
    switch strings.ToLower(s) { case "unix", "tcp", "http", "https": return true }
    return false
}

if err := sandbox.ValidateDockerHost(cfg.Docker.Host, allowPrivate); err != nil {
    if strings.Contains(err.Error(), "unsupported docker host scheme") { /* translate npipe/ssh/fd setups to tcp+TLS */ }
    return err
}

When it happens

Trigger: Configuring a docker host with an unsupported scheme such as "npipe:////./pipe/docker_engine" (Windows named pipe), "ssh://user@host", or "fd://" and calling ResolveEffectiveConfig / TestValidateDockerHost.

Common situations: Porting a Windows DOCKER_HOST (npipe://) to the Linux sandbox; using Docker's ssh:// transport expecting tunneling support; copying DOCKER_HOST verbatim from docker CLI configs that allow schemes this sandbox does not.

Related errors

• sandbox: docker host %q must include a scheme (unix:// or tc
• sandbox: docker unix socket path %q must be absolute
• sandbox: config is missing required fields: %s backend requi
• sandbox: remote docker host %q requires a TLS certificate di
• sandbox: docker network mode %q is not allowed; use "bridge"

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