AdguardTeam/AdGuardHome · error

setting gid: %w

Error message

setting gid: %w

What it means

The final step of setGroup: syscall.Setgid(gid) failed. Setgid requires root (or appropriate capabilities) and is one-shot — it typically fails with EPERM if the process isn't privileged, or EINVAL for an invalid gid.

Source

Thrown at internal/aghos/user_unix.go:25

	"os/user"
	"strconv"
	"syscall"
)

func setGroup(groupName string) (err error) {
	g, err := user.LookupGroup(groupName)
	if err != nil {
		return fmt.Errorf("looking up group: %w", err)
	}

	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 {

View on GitHub (pinned to b41aefbe51)

Solutions

1. Run the service as root or a user with CAP_SETGID (systemd: AmbientCapabilities=CAP_SETGID or set User=root)
2. In Docker, retain the capability: --cap-add SETGID
3. Remove or comment out the group: setting if running unprivileged
4. Ensure setGroup runs before any privilege drop, not after

// before starting unprivileged, check ability:
if syscall.Geteuid() != 0 { /* skip or demand CAP_SETGID for group config */ }

if err != nil && errors.Is(err, syscall.EPERM) { /* insufficient privilege: adjust service caps */ }

When it happens

Trigger: Running AdGuardHome as a non-root user while configuring a group: value in config; or running as root but inside a container missing CAP_SETGID; occasionally EINVAL from a negative or out-of-range gid.

Common situations: Systemd service running as DynamicUser/non-root without CAP_SETGID; Docker with dropped capabilities (--cap-drop=ALL); trying to change group after already dropping privileges.

Related errors

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

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