{"record":{"id":"0ba523e60f13f501","repo":"cloudflare/cloudflared","slug":"unix-socket-must-be-used-exclusively","errorCode":null,"errorMessage":"--unix-socket must be used exclusively.","messagePattern":"--unix-socket must be used exclusively\\.","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"config/configuration.go","lineNumber":158,"sourceCode":"\t\tlogDir := DefaultLogDirectory()\n\t\t_ = os.MkdirAll(logDir, os.ModePerm) // try and create it. Doesn't matter if it succeed or not, only byproduct will be no logs\n\n\t\tc := Root{\n\t\t\tLogDirectory: logDir,\n\t\t}\n\t\tif err := yaml.NewEncoder(file).Encode(&c); err != nil {\n\t\t\treturn \"\"\n\t\t}\n\t}\n\n\treturn path\n}\n\n// ValidateUnixSocket ensures --unix-socket param is used exclusively\n// i.e. it fails if a user specifies both --url and --unix-socket\nfunc ValidateUnixSocket(c *cli.Context) (string, error) {\n\tif c.IsSet(\"unix-socket\") && (c.IsSet(\"url\") || c.NArg() > 0) {\n\t\treturn \"\", errors.New(\"--unix-socket must be used exclusively.\")\n\t}\n\treturn c.String(\"unix-socket\"), nil\n}\n\n// ValidateUrl will validate url flag correctness. It can be either from --url or argument\n// Notice ValidateUnixSocket, it will enforce --unix-socket is not used with --url or argument\nfunc ValidateUrl(c *cli.Context, allowURLFromArgs bool) (*url.URL, error) {\n\tvar url = c.String(\"url\")\n\tif allowURLFromArgs && c.NArg() > 0 {\n\t\tif c.IsSet(\"url\") {\n\t\t\treturn nil, errors.New(\"Specified origin urls using both --url and argument. Decide which one you want, I can only support one.\")\n\t\t}\n\t\turl = c.Args().Get(0)\n\t}\n\tvalidUrl, err := validation.ValidateUrl(url)\n\treturn validUrl, err\n}\n","sourceCodeStart":140,"sourceCodeEnd":176,"githubUrl":"https://github.com/cloudflare/cloudflared/blob/2253eeeb25a44a713a4b60b8ba1e1b3f377d1a0f/config/configuration.go#L140-L176","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Remove either the --unix-socket flag or the --url flag / positional URL argument so only one origin mechanism is specified","Check the config file (~/.cloudflared/config.yml) for a lingering 'url:' key when using --unix-socket on the command line","If you want a Unix socket origin, replace --url with --unix-socket=/path/to/socket instead of combining them"],"exampleFix":"// before\ncloudflared tunnel --url http://localhost:8080 --unix-socket /tmp/app.sock\n// after\ncloudflared tunnel --unix-socket /tmp/app.sock","handlingStrategy":"validation","validationCode":"if c.IsSet(\"unix-socket\") && (c.IsSet(\"url\") || c.NArg() > 0) {\n    return errors.New(\"pass either --unix-socket or --url/argument, not both\")\n}","typeGuard":"func usesUnixSocketExclusively(c *cli.Context) bool {\n    return c.IsSet(\"unix-socket\") && !c.IsSet(\"url\") && c.NArg() == 0\n}","tryCatchPattern":null,"preventionTips":["Audit config files and launch scripts for both 'url' and 'unix-socket' keys","Prefer one canonical origin mechanism per tunnel in your deployment tooling","Test CLI invocations with `cloudflared tunnel --help` semantics before shipping scripts"],"tags":["cli","config","conflicting-flags"],"backgroundTag":"mutually-exclusive-flags","analyzedSha":"2253eeeb25a44a713a4b60b8ba1e1b3f377d1a0f","analyzedAt":"2026-09-06T04:14:33.757Z","contentChangedAt":"2026-09-06T04:14:33.757Z","schemaVersion":2},"datasetVersion":"2026-09-14T00:17:10.932Z"}