{"record":{"id":"9016c2527662308f","repo":"caddyserver/caddy","slug":"invalid-file-descriptor-v","errorCode":null,"errorMessage":"invalid file descriptor: %v","messagePattern":"invalid file descriptor: (.+?)","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"listen.go","lineNumber":40,"sourceCode":"\t\"net\"\n\t\"os\"\n\t\"slices\"\n\t\"strconv\"\n\t\"sync\"\n\t\"sync/atomic\"\n\t\"time\"\n\n\t\"go.uber.org/zap\"\n)\n\nfunc listenReusable(ctx context.Context, lnKey string, network, address string, config net.ListenConfig) (any, error) {\n\tvar socketFile *os.File\n\n\tfd := slices.Contains([]string{\"fd\", \"fdgram\"}, network)\n\tif fd {\n\t\tsocketFd, err := strconv.ParseUint(address, 0, strconv.IntSize)\n\t\tif err != nil {\n\t\t\treturn nil, fmt.Errorf(\"invalid file descriptor: %v\", err)\n\t\t}\n\n\t\tfunc() {\n\t\t\tsocketFilesMu.Lock()\n\t\t\tdefer socketFilesMu.Unlock()\n\n\t\t\tsocketFdWide := uintptr(socketFd)\n\t\t\tvar ok bool\n\n\t\t\tsocketFile, ok = socketFiles[socketFdWide]\n\n\t\t\tif !ok {\n\t\t\t\tsocketFile = os.NewFile(socketFdWide, lnKey)\n\t\t\t\tif socketFile != nil {\n\t\t\t\t\tsocketFiles[socketFdWide] = socketFile\n\t\t\t\t}\n\t\t\t}\n\t\t}()","sourceCodeStart":22,"sourceCodeEnd":58,"githubUrl":"https://github.com/caddyserver/caddy/blob/50e54ee279aa1e504fe218ca49ab6ae16c100410/listen.go#L22-L58","documentation":"When the listen network is 'fd' or 'fdgram', Caddy interprets the address as an integer file descriptor number passed to the process (socket activation). This error means the address could not be parsed as an unsigned integer of the platform's int size (ParseUint with base 0, so decimal/hex/octal literals are accepted, but non-numeric strings are not).","triggerScenarios":"Configuring listen network 'fd' with a non-numeric address such as 'fd:3', 'socket', '3rd', an empty string, or a value larger than the max int on the platform.","commonSituations":"Migrating a config from systemd socket activation where the address was written as a label or with a colon prefix; typos; or templates that leave the fd placeholder empty.","solutions":["Set the address to the bare descriptor number, e.g. network 'fd', address '3'.","Base-0 prefixes are allowed: '0x3' works if you prefer hex.","If you meant a unix path or TCP address, use network 'unix' or 'tcp' instead of 'fd'.","Verify the descriptor is actually passed to the process (systemd sockets, exec inheritance) — but this error is purely about numeric parsing."],"exampleFix":"// before\n{\n  listen fd:3\n}\n// after\n{\n  listen fd 3\n}","handlingStrategy":"validation","validationCode":"func validFdAddress(addr string) bool {\n    _, err := strconv.ParseUint(addr, 0, strconv.IntSize)\n    return err == nil\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Feed fd addresses from integer variables, never interpolated labels.","Reserve the 'fd' network strictly for socket-activated descriptors."],"tags":["file-descriptor","socket-activation","listen","config"],"backgroundTag":null,"analyzedSha":"50e54ee279aa1e504fe218ca49ab6ae16c100410","analyzedAt":"2026-08-15T09:20:21.641Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}