AdguardTeam/AdGuardHome · error

setting uid: %w

Error message

setting uid: %w

What it means

The final step of setUser: syscall.Setuid(uid) failed. Setuid requires root or CAP_SETUID and fails with EPERM when unprivileged, EINVAL for an invalid uid; it is also irreversible, so ordering matters in privilege-dropping code.

Source

Thrown at internal/aghos/user_unix.go:44

	}

	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. Run as root or grant CAP_SETUID (systemd: AmbientCapabilities=CAP_SETUID, Docker: --cap-add SETUID)
2. Remove the user: config option if the service is meant to run unprivileged
3. Ensure setUser is invoked before any other privilege-dropping step

if syscall.Geteuid() != 0 { /* skip user switching or require CAP_SETUID */ }

if err != nil && errors.Is(err, syscall.EPERM) { /* grant CAP_SETUID or drop user: config */ }

When it happens

Trigger: Running the process as non-root while a user: is configured; containers lacking CAP_SETUID; attempting to change uid after privileges were already dropped; uid out of range for the kernel.

Common situations: Systemd units running as unprivileged users with user: still set in config; Docker with dropped capabilities; security-hardened environments blocking identity changes.

Related errors

• setting gid: %w
• looking up user: %w
• %s: not supported on %s: %w
• looking up group: %w
• parsing gid: %w

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