{"record":{"id":"2e73c553acbb8906","repo":"Tencent/WeKnora","slug":"sandbox-unsupported-docker-host-scheme-q","errorCode":null,"errorMessage":"sandbox: unsupported docker host scheme %q","messagePattern":"sandbox: unsupported docker host scheme %q","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"internal/sandbox/docker_engine.go","lineNumber":282,"sourceCode":"\tscheme, address, found := strings.Cut(trimmed, \"://\")\n\tif !found {\n\t\treturn fmt.Errorf(\n\t\t\t\"sandbox: docker host %q must include a scheme (unix:// or tcp://)\", host)\n\t}\n\tswitch strings.ToLower(scheme) {\n\tcase \"unix\":\n\t\tif !strings.HasPrefix(address, \"/\") {\n\t\t\treturn fmt.Errorf(\"sandbox: docker unix socket path %q must be absolute\", address)\n\t\t}\n\t\treturn nil\n\tcase \"tcp\", \"http\", \"https\":\n\t\t// The guard speaks HTTP; the daemon's TCP endpoint is an HTTP\n\t\t// endpoint, so the check is the same one every other backend gets.\n\t\treturn ValidateOutboundURLWithPolicy(\n\t\t\t\"http://\"+address, OutboundURLPolicy{AllowPrivate: allowPrivate},\n\t\t)\n\tdefault:\n\t\treturn fmt.Errorf(\"sandbox: unsupported docker host scheme %q\", scheme)\n\t}\n}\n\n// ValidateDockerRemoteTLS requires client certificates for a TCP daemon.\n// A remote Engine API that accepts container creation is a root shell on\n// that host; plaintext tcp://2375 is not an acceptable way to reach it.\n// Unix sockets are local to the WeKnora process and do not use TLS.\nfunc ValidateDockerRemoteTLS(host, tlsCertPath string) error {\n\ttrimmed := strings.TrimSpace(host)\n\tif trimmed == \"\" {\n\t\treturn nil\n\t}\n\tscheme, _, found := strings.Cut(trimmed, \"://\")\n\tif !found {\n\t\treturn nil\n\t}\n\tswitch strings.ToLower(scheme) {\n\tcase \"tcp\", \"http\", \"https\":","sourceCodeStart":264,"sourceCodeEnd":300,"githubUrl":"https://github.com/Tencent/WeKnora/blob/988cbb03305e055d8ebb7d46d9ac6cc0803cd074/internal/sandbox/docker_engine.go#L264-L300","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Replace the scheme with tcp://host:port or https:// and run the daemon's TCP endpoint (with TLS, see ValidateDockerRemoteTLS)","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","Drop ssh:// in favor of an HTTPS-secured remote Engine API endpoint","Check the lowercase scheme — validation lowercases the scheme, so \"TCP://\" is fine but typos like \"tcp ://\" are not"],"exampleFix":"// before\nHost: \"ssh://user@build-host\"\n// after\nHost: \"tcp://build-host:2376\" // with TLS cert dir configured","handlingStrategy":"validation","validationCode":"scheme, _, _ := strings.Cut(strings.TrimSpace(cfg.Docker.Host), \"://\")\nswitch strings.ToLower(scheme) {\ncase \"\", \"unix\", \"tcp\", \"http\", \"https\":\ndefault:\n    return fmt.Errorf(\"unsupported docker scheme %q; use tcp:// or https://\", scheme)\n}","typeGuard":"func schemeSupported(host string) bool {\n    s, _, ok := strings.Cut(strings.TrimSpace(host), \"://\")\n    if !ok { return true }\n    switch strings.ToLower(s) { case \"unix\", \"tcp\", \"http\", \"https\": return true }\n    return false\n}","tryCatchPattern":"if err := sandbox.ValidateDockerHost(cfg.Docker.Host, allowPrivate); err != nil {\n    if strings.Contains(err.Error(), \"unsupported docker host scheme\") { /* translate npipe/ssh/fd setups to tcp+TLS */ }\n    return err\n}","preventionTips":["Avoid docker-CLI-only transports (npipe://, ssh://, fd://) in sandbox configs","For remote daemons always use https:// (or tcp:// with the TLS cert dir)","Centralize host construction in one helper that only emits supported schemes"],"tags":["sandbox","docker","configuration","url-validation"],"backgroundTag":"unsupported-url-scheme","analyzedSha":"988cbb03305e055d8ebb7d46d9ac6cc0803cd074","analyzedAt":"2026-09-02T14:41:08.344Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-08T10:18:20.063Z"}