cloudflare/cloudflared · error

--unix-socket must be used exclusively.

Error message

--unix-socket must be used exclusively.

What it means

ValidateUnixSocket enforces that the --unix-socket flag is used exclusively: a user of cloudflared may not specify --unix-socket together with --url or with a positional URL argument. The library throws this error to prevent ambiguous origin configuration, since both flags describe the same origin service.

Source

Thrown at config/configuration.go:158

		logDir := DefaultLogDirectory()
		_ = os.MkdirAll(logDir, os.ModePerm) // try and create it. Doesn't matter if it succeed or not, only byproduct will be no logs

		c := Root{
			LogDirectory: logDir,
		}
		if err := yaml.NewEncoder(file).Encode(&c); err != nil {
			return ""
		}
	}

	return path
}

// ValidateUnixSocket ensures --unix-socket param is used exclusively
// i.e. it fails if a user specifies both --url and --unix-socket
func ValidateUnixSocket(c *cli.Context) (string, error) {
	if c.IsSet("unix-socket") && (c.IsSet("url") || c.NArg() > 0) {
		return "", errors.New("--unix-socket must be used exclusively.")
	}
	return c.String("unix-socket"), nil
}

// ValidateUrl will validate url flag correctness. It can be either from --url or argument
// Notice ValidateUnixSocket, it will enforce --unix-socket is not used with --url or argument
func ValidateUrl(c *cli.Context, allowURLFromArgs bool) (*url.URL, error) {
	var url = c.String("url")
	if allowURLFromArgs && c.NArg() > 0 {
		if c.IsSet("url") {
			return nil, errors.New("Specified origin urls using both --url and argument. Decide which one you want, I can only support one.")
		}
		url = c.Args().Get(0)
	}
	validUrl, err := validation.ValidateUrl(url)
	return validUrl, err
}

View on GitHub (pinned to 2253eeeb25)

Solutions

1. Remove either the --unix-socket flag or the --url flag / positional URL argument so only one origin mechanism is specified
2. Check the config file (~/.cloudflared/config.yml) for a lingering 'url:' key when using --unix-socket on the command line
3. If you want a Unix socket origin, replace --url with --unix-socket=/path/to/socket instead of combining them

Example fix

// before
cloudflared tunnel --url http://localhost:8080 --unix-socket /tmp/app.sock
// after
cloudflared tunnel --unix-socket /tmp/app.sock

if c.IsSet("unix-socket") && (c.IsSet("url") || c.NArg() > 0) {
    return errors.New("pass either --unix-socket or --url/argument, not both")
}

func usesUnixSocketExclusively(c *cli.Context) bool {
    return c.IsSet("unix-socket") && !c.IsSet("url") && c.NArg() == 0
}

When it happens

Trigger: parseSingleOriginService calls ValidateUnixSocket with a cli.Context where both the 'unix-socket' flag is set and either the 'url' flag is set or at least one positional argument (the URL) is provided.

Common situations: Users migrating from --url to --unix-socket leave the old --url flag in their config file or command line; shell scripts or systemd units that append both flags; config files with both keys set while CLI flags are merged in.

Understand the failure class

Background: "mutually exclusive" flag errors: what "can't supply both nx and xx", "--raw is not compatible with -i" and "cannot be used with" mean, and how to fix them — this error's family across 29 libraries.

Related errors

• Specified origin urls using both --url and argument. Decide
• ErrURLIncompatibleWithIngress
• hostname and url shouldn't match. See --help for more inform
• The tunnel credentials file should be .json but you gave a .
• Cannot parse tag value %s

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