What causes "sandbox: docker unix socket path %q must be absolute" in Tencent/WeKnora?

Use a full absolute path: unix:///var/run/docker.sock (note the three slashes: empty host + absolute path)

sandbox: docker unix socket path %q must be absolute

Error message

sandbox: docker unix socket path %q must be absolute

What it means

ValidateDockerHost accepts a unix:// scheme but requires the address portion to be an absolute filesystem path starting with '/'. A relative path like unix://docker.sock or unix://run/docker.sock cannot be resolved reliably by the Docker client, so this error is thrown.

Source

Thrown at internal/sandbox/docker_engine.go:272

//
// A TCP endpoint gets the same outbound treatment as any other workspace-
// supplied URL: a daemon socket accepts container creation, so an admin who
// can point it anywhere can make WeKnora talk to an arbitrary internal
// service. Unix sockets are local by definition and only have to be absolute.
func ValidateDockerHost(host string, allowPrivate bool) error {
	trimmed := strings.TrimSpace(host)
	if trimmed == "" {
		return nil
	}
	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 {

View on GitHub (pinned to 988cbb0330)

Solutions

Use a full absolute path: unix:///var/run/docker.sock (note the three slashes: empty host + absolute path)
Resolve the socket path with an absolute reference, e.g. filepath.Join to an absolute base before formatting the host string
Verify the socket file exists and is readable at that absolute path
If intending a remote daemon, switch to tcp://host:port instead of unix://

Example fix

// before
Host: "unix://docker.sock"
// after
Host: "unix:///var/run/docker.sock"

Defensive patterns

Strategy: validation

Validate before calling

if strings.HasPrefix(strings.ToLower(strings.TrimSpace(cfg.Docker.Host)), "unix://") {
    addr := strings.TrimPrefix(strings.TrimSpace(cfg.Docker.Host), "unix://")
    if !strings.HasPrefix(addr, "/") { return fmt.Errorf("unix socket path must be absolute: %q", addr) }
}

Type guard

func isAbsoluteUnixSocketHost(host string) bool {
    _, addr, found := strings.Cut(strings.TrimSpace(host), "://")
    return found && strings.HasPrefix(addr, "/")
}

Try / catch

if err := sandbox.ValidateDockerHost(cfg.Docker.Host, allowPrivate); err != nil {
    if strings.Contains(err.Error(), "must be absolute") { /* fix path to leading-slash absolute form */ }
    return err
}

Prevention

Remember the three-slash form: unix:///var/run/docker.sock (empty host + absolute path)
Build socket paths with filepath.Abs before formatting the host string
Verify the socket file exists at the absolute path on the host running the guard

When it happens

Trigger: Configuring a docker host as unix:// followed by a relative path — e.g. "unix://docker.sock", "unix://./sock", "unix://run/docker.sock" — then calling ResolveEffectiveConfig or TestValidateDockerHost.

Common situations: Writing unix://docker.sock by analogy with URLs where the host segment is omitted; environments where the daemon socket lives at a custom path and only the filename was configured; confusion between URL host/path semantics and filesystem paths.

Related errors

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