AdguardTeam/AdGuardHome · critical

initializing auth module: %w

Error message

initializing auth module: %w

What it means

AdGuard Home could not initialize its authentication/user module (aghnet/home auth init). The users module validates the configured user list (name/password hashes) and fails when the configuration is invalid.

Source

Thrown at internal/home/home.go:1123

		baseLogger.WarnContext(ctx, "authratelimiter is disabled")
		rateLimiter = emptyRateLimiter{}
	}

	dataDirPath := filepath.Join(workDir, dataDir)
	auth, err = newAuth(ctx, &authConfig{
		baseLogger:      baseLogger,
		mux:             mux,
		rateLimiter:     rateLimiter,
		trustedProxies:  netutil.SliceSubnetSet(netutil.UnembedPrefixes(config.DNS.TrustedProxies)),
		dbFilename:      filepath.Join(dataDirPath, sessionsDBName),
		doHRoutes:       config.HTTPConfig.DoH.Routes,
		users:           config.Users,
		sessionTTL:      time.Duration(config.HTTPConfig.SessionTTL),
		isGLiNet:        isGLiNet,
		gliNetTokenRoot: glTokenRoot,
	})
	if err != nil {
		return nil, fmt.Errorf("initializing auth module: %w", err)
	}

	config.Users = nil

	return auth, nil
}

func (c *configuration) anonymizer() (ipmut *aghnet.IPMut) {
	var anonFunc aghnet.IPMutFunc
	if c.DNS.AnonymizeClientIP {
		anonFunc = querylog.AnonymizeIP
	}

	return aghnet.NewIPMut(anonFunc)
}

// permCheckHelp is printed when binding to privileged ports is not permitted.
const permCheckHelp = `Permission check failed.

View on GitHub (pinned to b41aefbe51)

Solutions

1. Inspect the wrapped error and the users: section of yaml.yaml for malformed password hashes
2. Fix or remove the offending user entries; a fresh hash can be generated with bcrypt
3. As a last resort, remove the users list to recreate the first user through the install wizard

// Validate user password hashes before passing config.Users:
for _, u := range cfg.Users {
    if u.Name == "" { return errors.New("empty username") }
    if _, err := bcrypt.Cost([]byte(u.PasswordHash)); err != nil {
        return fmt.Errorf("user %s: bad hash: %w", u.Name, err)
    }
}

When it happens

Trigger: Calling initUsers during run when config.Users contains malformed entries — e.g. invalid bcrypt password hash strings, empty username, or unsupported hash format after a config migration.

Common situations: Hand-edited YAML config with broken password hashes, config migrated from a very old version, or a corrupted yaml.yaml after disk issues.

Related errors

• generating password hash: %w
• duplicated values: %v
• json duration is nil
• networksetup failed to set dns servers: %w
• found no dns servers in %s

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