What causes "Error validating --unix-socket" in cloudflare/cloudflared?

Verify the socket file exists: ls -l should show type 's' before starting cloudflared (or start the origin first).

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.

Solutions

Verify the socket file exists: ls -l <path> should show type 's' before starting cloudflared (or start the origin first).
Pass an absolute path to the socket, not a relative one.
Ensure the user running cloudflared has read/write permission on the socket.
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

Defensive patterns

Strategy: validation

Validate before calling

// 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
}

Prevention

Start the origin service before cloudflared so the socket file exists.
Use absolute socket paths under a writable runtime directory (e.g. /run).
Ensure the cloudflared user has read/write permission on the socket.
Confirm the file is actually a socket (mode 's') rather than a regular file.

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

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

Appendix: 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)