AdguardTeam/AdGuardHome · error

looking up user: %w

Error message

looking up user: %w

What it means

setUser resolves a username via os/user.Lookup before calling syscall.Setuid; this error means the lookup failed — typically user.UnknownUserError (no such user) or a backend failure reading the user database.

Source

Thrown at internal/aghos/user_unix.go:34

	}

	gid, err := strconv.Atoi(g.Gid)
	if err != nil {
		return fmt.Errorf("parsing gid: %w", err)
	}

	err = syscall.Setgid(gid)
	if err != nil {
		return fmt.Errorf("setting gid: %w", err)
	}

	return nil
}

func setUser(userName string) (err error) {
	u, err := user.Lookup(userName)
	if err != nil {
		return fmt.Errorf("looking up user: %w", err)
	}

	uid, err := strconv.Atoi(u.Uid)
	if err != nil {
		return fmt.Errorf("parsing uid: %w", err)
	}

	err = syscall.Setuid(uid)
	if err != nil {
		return fmt.Errorf("setting uid: %w", err)
	}

	return nil
}

View on GitHub (pinned to b41aefbe51)

Solutions

1. Verify the user exists: getent passwd <name>
2. Fix the typo or create the user, then restart
3. In containers, create the user in the Dockerfile or use docker --user with a numeric uid
4. Trim whitespace in the config value and re-check spelling

if _, err := user.Lookup(userName); err != nil { /* fix config: user missing on this host */ }

func isUnknownUser(err error) bool { var e user.UnknownUserError; return errors.As(err, &e) }

if err != nil {
    var unknown user.UnknownUserError
    if errors.As(err, &unknown) { /* correct username or create user */ }
}

When it happens

Trigger: Configuring AdGuardHome with a user: value that doesn't exist on the host or inside the container image; NSS/LDAM lookup failures; CGO-disabled builds parsing /etc/passwd directly encountering malformed content.

Common situations: Typos in the username in config; minimal Docker images without the user; LDAP environments invisible to the pure-Go resolver; usernames with trailing whitespace from YAML formatting.

Related errors

• looking up group: %w
• parsing gid: %w
• parsing uid: %w
• setting uid: %w
• setting gid: %w

AI-assisted analysis of AdguardTeam/AdGuardHome@b41aefbe51 (2026-08-27). Data as JSON: /api/errors/b5a17bc8db3e42ee. Report an issue: GitHub.