{"record":{"id":"7283e251caa7e821","repo":"hashicorp/nomad","slug":"error-looking-up-user-q-w","errorCode":null,"errorMessage":"error looking up user %q: %w","messagePattern":"error looking up user %q: %w","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"helper/users/lookup.go","lineNumber":34,"sourceCode":")\n\nvar globalCache = newCache()\n\n// Lookup returns the user.User entry associated with the given username.\n//\n// Values are cached up to 1 hour, or 1 minute for failure cases.\nfunc Lookup(username string) (*user.User, error) {\n\treturn globalCache.GetUser(username)\n}\n\n// LookupUnix returns the UID, GID, and home directory for username or returns\n// an error. ID values are int to work well with Go library functions.\n//\n// Will always fail on Windows and Plan 9.\nfunc LookupUnix(username string) (int, int, string, error) {\n\tu, err := Lookup(username)\n\tif err != nil {\n\t\treturn 0, 0, \"\", fmt.Errorf(\"error looking up user %q: %w\", username, err)\n\t}\n\n\tuid, err := strconv.Atoi(u.Uid)\n\tif err != nil {\n\t\treturn 0, 0, \"\", fmt.Errorf(\"error parsing uid: %w\", err)\n\t}\n\n\tgid, err := strconv.Atoi(u.Gid)\n\tif err != nil {\n\t\treturn 0, 0, \"\", fmt.Errorf(\"error parsing gid: %w\", err)\n\t}\n\n\treturn uid, gid, u.HomeDir, nil\n}\n\n// lock is used to serialize all user lookup at the process level, because\n// some NSS implementations are not concurrency safe\nvar lock sync.Mutex","sourceCodeStart":16,"sourceCodeEnd":52,"githubUrl":"https://github.com/hashicorp/nomad/blob/482b49bf1aec006f089bcfc7e632d8f6ac303e5e/helper/users/lookup.go#L16-L52","documentation":"LookupUnix resolves a username to uid/gid/home via user.Lookup and wraps any lookup failure with the username and the underlying error. It always fails on Windows and Plan 9, and otherwise indicates the OS user database has no such user or the lookup mechanism failed.","triggerScenarios":"Calling users.LookupUnix(username) (directly or via LookupUser, chownDestination, writeFileFor, setSocketOwner) with a username that user.Lookup cannot resolve — unknown user, NSS misconfiguration, or an unsupported platform.","commonSituations":"Config references a service user that was never created on the host; running in a minimal/chroot container image without /etc/passwd entries; stale config after the user was removed.","solutions":["Create the user on the host (useradd) or fix the username in configuration","Ensure /etc/passwd and /etc/nsswitch.conf are correct in the runtime environment","On Windows/Plan 9, use a platform-independent lookup path — LookupUnix is documented to always fail there"],"exampleFix":"// before\nuid, gid, home, err := users.LookupUnix(\"nomad-agent\")\n// after\nif _, lookupErr := user.Lookup(\"nomad-agent\"); lookupErr != nil {\n\tlog.Fatalf(\"required OS user missing: %v\", lookupErr)\n}\nuid, gid, home, err := users.LookupUnix(\"nomad-agent\")","handlingStrategy":"validation","validationCode":"if runtime.GOOS == \"windows\" || runtime.GOOS == \"plan9\" {\n\treturn errors.New(\"LookupUnix unsupported on this platform\")\n}\nif _, err := user.Lookup(username); err != nil {\n\treturn fmt.Errorf(\"OS user %q must exist before start: %w\", username, err)\n}\nuid, gid, home, err := users.LookupUnix(username)","typeGuard":"func userExists(username string) bool {\n\t_, err := user.Lookup(username)\n\treturn err == nil\n}","tryCatchPattern":"uid, gid, home, err := users.LookupUnix(username)\nif err != nil {\n\tvar uerr *user.UnknownUserError\n\tif errors.As(err, &uerr) || strings.Contains(err.Error(), \"error looking up user\") {\n\t\treturn fmt.Errorf(\"create OS user %q or fix config: %w\", username, err)\n\t}\n\treturn err\n}","preventionTips":["Provision required OS users in install/startup scripts before the service runs","Check /etc/passwd and nsswitch.conf in container images","Gate LookupUnix behind a runtime.GOOS check; it always fails on Windows/Plan 9","Validate configured usernames at config load, not deep in file-chown logic"],"tags":["unix","user-lookup","os","permissions"],"backgroundTag":"unknown-user-lookup-failed","analyzedSha":"482b49bf1aec006f089bcfc7e632d8f6ac303e5e","analyzedAt":"2026-09-04T07:54:14.808Z","contentChangedAt":"2026-09-04T07:54:14.808Z","schemaVersion":2},"datasetVersion":"2026-09-08T10:18:20.063Z"}