{"record":{"id":"b0fb6155cedd890a","repo":"grpc/grpc-go","slug":"invalid-non-empty-authority-v","errorCode":null,"errorMessage":"invalid (non-empty) authority: %v","messagePattern":"invalid \\(non-empty\\) authority: (.+?)","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"internal/resolver/unix/unix.go","lineNumber":38,"sourceCode":"package unix\n\nimport (\n\t\"fmt\"\n\n\t\"google.golang.org/grpc/internal/transport/networktype\"\n\t\"google.golang.org/grpc/resolver\"\n)\n\nconst unixScheme = \"unix\"\nconst unixAbstractScheme = \"unix-abstract\"\n\ntype builder struct {\n\tscheme string\n}\n\nfunc (b *builder) Build(target resolver.Target, cc resolver.ClientConn, _ resolver.BuildOptions) (resolver.Resolver, error) {\n\tif target.URL.Host != \"\" {\n\t\treturn nil, fmt.Errorf(\"invalid (non-empty) authority: %v\", target.URL.Host)\n\t}\n\n\t// gRPC was parsing the dial target manually before PR #4817, and we\n\t// switched to using url.Parse() in that PR. To avoid breaking existing\n\t// resolver implementations we ended up stripping the leading \"/\" from the\n\t// endpoint. This obviously does not work for the \"unix\" scheme. Hence we\n\t// end up using the parsed URL instead.\n\tendpoint := target.URL.Path\n\tif endpoint == \"\" {\n\t\tendpoint = target.URL.Opaque\n\t}\n\taddr := resolver.Address{Addr: endpoint}\n\tif b.scheme == unixAbstractScheme {\n\t\t// We can not prepend \\0 as c++ gRPC does, as in Golang '@' is used to signify we do\n\t\t// not want trailing \\0 in address.\n\t\taddr.Addr = \"@\" + addr.Addr\n\t}\n\tcc.UpdateState(resolver.State{Addresses: []resolver.Address{networktype.Set(addr, \"unix\")}})","sourceCodeStart":20,"sourceCodeEnd":56,"githubUrl":"https://github.com/grpc/grpc-go/blob/0c51461d27177d997e14c642fe18c11668fc09a3/internal/resolver/unix/unix.go#L20-L56","documentation":"The unix and unix-abstract resolvers expect the dial target's URL to carry no authority (host) component — the socket path lives in the URL path or opaque part (e.g. \"unix:///tmp/sock\" or \"unix:tmp/sock\"). At unix.go:36-39, if target.URL.Host is non-empty the builder refuses to build. This prevents ambiguity between authority and socket path.","triggerScenarios":"Triggered when the unix/unix-abstract resolver's Build receives a target whose URL.Host is set, e.g. \"unix://localhost/tmp/sock\" (authority 'localhost'), which is a common mis-formatting of unix targets.","commonSituations":"A developer writes the target as \"unix://<host>/path\" out of habit from http-style URLs, or a config template inserts an authority. The correct forms are \"unix:///path/to/sock\" (three slashes, empty authority) or \"unix:path/to/sock\".","solutions":["Use the empty-authority form: \"unix:///absolute/path/to/socket\".","Or use the opaque form: \"unix:relative/path\".","Remove any host/authority segment between 'unix://' and the path."],"exampleFix":"// before:\n//   conn, err := grpc.Dial(\"unix://localhost/tmp/x.sock\", opts)\n//   // error: invalid (non-empty) authority: localhost\n\n// after:\n//   conn, err := grpc.Dial(\"unix:///tmp/x.sock\", opts)","handlingStrategy":"validation","validationCode":"package main\n\nimport (\n\t\"fmt\"\n\t\"net/url\"\n\t\"strings\"\n)\n\n// validateUnixTarget ensures the authority is empty for unix/unix-abstract.\nfunc validateUnixTarget(raw string) error {\n\tu, err := url.Parse(raw)\n\tif err != nil {\n\t\treturn fmt.Errorf(\"unparseable unix target %q: %w\", raw, err)\n\t}\n\tif u.Host != \"\" {\n\t\treturn fmt.Errorf(\"unix target must have empty authority, got %q\", u.Host)\n\t}\n\tif u.Path == \"\" && u.Opaque == \"\" {\n\t\treturn fmt.Errorf(\"unix target has no socket path\")\n\t}\n\treturn nil\n}\n\nvar _ = strings.TrimSpace\n\n// func main() { _ = validateUnixTarget(\"unix:///tmp/x.sock\") }","typeGuard":null,"tryCatchPattern":"// grpc.Dial surfaces this synchronously from the unix resolver's Build.\n//\n//   conn, err := grpc.Dial(target, opts)\n//   if err != nil && strings.Contains(err.Error(), \"invalid (non-empty) authority\") {\n//       return fmt.Errorf(\"use unix:///path (empty authority), not unix://host/path\")\n//   }","preventionTips":["Use the three-slash form for absolute socket paths: unix:///path/to/sock.","Never insert an authority/host between 'unix://' and the path.","Validate UDS targets with url.Parse and assert Host == \"\"."],"tags":["resolver","unix","uds","addressing","grpc"],"backgroundTag":null,"analyzedSha":"0c51461d27177d997e14c642fe18c11668fc09a3","analyzedAt":"2026-08-11T14:49:15.055Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}