cloudflare/cloudflared · error

Error validating --unix-socket

Error message

Error validating --unix-socket

What it means

parseSingleOriginService validates the --unix-socket flag with config.ValidateUnixSocket and wraps failures as 'Error validating --unix-socket'. The flag value must resolve to a valid local unix socket path that cloudflared can proxy HTTP requests over.

Source

Thrown at ingress/ingress.go:185

	if c.IsSet(config.BastionFlag) {
		return newBastionService(), nil
	}
	if c.IsSet("url") {
		originURL, err := config.ValidateUrl(c, allowURLFromArgs)
		if err != nil {
			return nil, errors.Wrap(err, "Error validating origin URL")
		}
		if isHTTPService(originURL) {
			return &httpService{
				url: originURL,
			}, nil
		}
		return newTCPOverWSService(originURL), nil
	}
	if c.IsSet("unix-socket") {
		path, err := config.ValidateUnixSocket(c)
		if err != nil {
			return nil, errors.Wrap(err, "Error validating --unix-socket")
		}
		return &unixSocketPath{path: path, scheme: "http"}, nil
	}
	return nil, ErrNoIngressRulesCLI
}

// IsEmpty checks if there are any ingress rules.
func (ing Ingress) IsEmpty() bool {
	return len(ing.Rules) == 0
}

// IsSingleRule checks if the user only specified a single ingress rule.
func (ing Ingress) IsSingleRule() bool {
	return len(ing.Rules) == 1
}

// StartOrigins will start any origin services managed by cloudflared, e.g. proxy servers or Hello World.
func (ing Ingress) StartOrigins(

View on GitHub (pinned to 2253eeeb25)

Solutions

1. Verify the socket file exists: ls -l <path> should show type 's' before starting cloudflared (or start the origin first).
2. Pass an absolute path to the socket, not a relative one.
3. Ensure the user running cloudflared has read/write permission on the socket.
4. Use --url instead if the origin is served over TCP rather than a unix socket.

Example fix

// before
cloudflared tunnel --unix-socket ./app.sock
// after
cloudflared tunnel --unix-socket /run/myapp/app.sock

// Go: verify the socket exists and is a socket before passing --unix-socket
fi, err := os.Stat(sockPath)
if err != nil || fi.Mode()&os.ModeSocket == 0 {
	// path missing or not a unix socket; start the origin first or fix the path
}

When it happens

Trigger: Running cloudflared with `--unix-socket <path>` where the path fails validation: empty value, invalid path characters, or a path that does not name a usable unix domain socket for the origin service.

Common situations: Pointing --unix-socket at a regular file or a directory instead of a socket, the origin service not yet having created the socket, typos in the path, or permission problems on the socket path.

Understand the failure class

Background: "Invalid value" and "allowed values are" config errors: what your library rejected and how to fix it — this error's family across 41 libraries.

Related errors

• Error validating origin URL
• ErrURLIncompatibleWithIngress
• No configuration file was found. Please create one, or use t
• cloudflared tunnel rule expects a single argument, the URL t
• --unix-socket must be used exclusively.

AI-assisted analysis of cloudflare/cloudflared@2253eeeb25 (2026-09-06). Data as JSON: /api/errors/c2df7580f0d870cb. Report an issue: GitHub.