{"record":{"id":"73c72338fae03df5","repo":"Tencent/WeKnora","slug":"sandbox-docker-host-q-must-include-a-scheme-uni","errorCode":null,"errorMessage":"sandbox: docker host %q must include a scheme (unix:// or tcp://)","messagePattern":"sandbox: docker host %q must include a scheme \\(unix:// or tcp://\\)","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"internal/sandbox/docker_engine.go","lineNumber":266,"sourceCode":"\tdefault:\n\t\treturn false\n\t}\n}\n\n// ValidateDockerHost checks a daemon endpoint before it is stored or dialled.\n//\n// A TCP endpoint gets the same outbound treatment as any other workspace-\n// supplied URL: a daemon socket accepts container creation, so an admin who\n// can point it anywhere can make WeKnora talk to an arbitrary internal\n// service. Unix sockets are local by definition and only have to be absolute.\nfunc ValidateDockerHost(host string, allowPrivate bool) error {\n\ttrimmed := strings.TrimSpace(host)\n\tif trimmed == \"\" {\n\t\treturn nil\n\t}\n\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}","sourceCodeStart":248,"sourceCodeEnd":284,"githubUrl":"https://github.com/Tencent/WeKnora/blob/988cbb03305e055d8ebb7d46d9ac6cc0803cd074/internal/sandbox/docker_engine.go#L248-L284","documentation":"ValidateDockerHost checks that a configured docker host string is usable by the sandbox backend. After trimming, the host must contain a \"://\" separator separating a scheme from an address; bare values like \"localhost:2375\" or \"/var/run/docker.sock\" are rejected because the client cannot infer the transport.","triggerScenarios":"Setting the docker host config field to a value without a scheme — e.g. \"localhost:2375\", \"127.0.0.1:2375\", or a bare socket path — and calling ResolveEffectiveConfig or TestValidateDockerHost.","commonSituations":"Copying DOCKER_HOST-style values from tooling that accepts bare hosts; writing just the socket path instead of unix:///var/run/docker.sock; omitting tcp:// from a remote daemon address.","solutions":["Prefix the host with a scheme: use unix:///path/to/socket for local sockets or tcp://host:port for remote daemons","Prefer https:// (or tcp:// with TLS configured) for remote daemons over plaintext tcp://","Re-run ResolveEffectiveConfig after fixing to catch any subsequent validation errors (TLS, network mode)","Note that empty/whitespace hosts pass (they fall back to defaults) — only non-empty scheme-less strings error"],"exampleFix":"// before\nHost: \"localhost:2375\"\n// after\nHost: \"tcp://localhost:2375\" // or \"unix:///var/run/docker.sock\"","handlingStrategy":"validation","validationCode":"h := strings.TrimSpace(cfg.Docker.Host)\nif h != \"\" && !strings.Contains(h, \"://\") {\n    return fmt.Errorf(\"docker host %q needs a scheme: unix:// or tcp://\", h)\n}\nif err := sandbox.ValidateDockerHost(h, true); err != nil { return err }","typeGuard":"func hasValidHostScheme(host string) bool {\n    t := strings.TrimSpace(host)\n    if t == \"\" { return true }\n    _, _, ok := strings.Cut(t, \"://\")\n    return ok\n}","tryCatchPattern":"if err := sandbox.ValidateDockerHost(cfg.Docker.Host, allowPrivate); err != nil {\n    if strings.Contains(err.Error(), \"must include a scheme\") { cfg.Docker.Host = \"unix://\" + cfg.Docker.Host }\n    return err\n}","preventionTips":["Always write full URLs: unix:///var/run/docker.sock or tcp://host:2376","Never copy bare DOCKER_HOST values from tools that accept scheme-less hosts","Run ValidateDockerHost in config load tests to catch regressions"],"tags":["sandbox","docker","configuration","url-validation"],"backgroundTag":"missing-url-scheme","analyzedSha":"988cbb03305e055d8ebb7d46d9ac6cc0803cd074","analyzedAt":"2026-09-02T14:41:08.344Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-08T10:18:20.063Z"}