AdguardTeam/AdGuardHome · error

os.MkdirAll: %s: %w

Error message

os.MkdirAll: %s: %w

What it means

Disabling the systemd-resolved DNS stub listener required creating the parent directory of resolvedConfPath (e.g. /etc/systemd/resolved.conf.d) and os.MkdirAll failed. Typical causes are missing privileges or a read-only filesystem.

Source

Thrown at internal/home/controlinstall.go:333

	resolvedConfPath = "/etc/systemd/resolved.conf.d/adguardhome.conf"
	resolvedConfData = `[Resolve]
DNS=127.0.0.1
DNSStubListener=no
`
)
const resolvConfPath = "/etc/resolv.conf"

// disableDNSStubListener deactivates DNSStubListerner and returns an error, if
// any.  cmdCons must not be nil.
func disableDNSStubListener(
	ctx context.Context,
	l *slog.Logger,
	cmdCons executil.CommandConstructor,
) (err error) {
	dir := filepath.Dir(resolvedConfPath)
	err = os.MkdirAll(dir, 0o755)
	if err != nil {
		return fmt.Errorf("os.MkdirAll: %s: %w", dir, err)
	}

	err = os.WriteFile(resolvedConfPath, []byte(resolvedConfData), 0o644)
	if err != nil {
		return fmt.Errorf("os.WriteFile: %s: %w", resolvedConfPath, err)
	}

	_ = os.Rename(resolvConfPath, resolvConfPath+".backup")
	err = os.Symlink("/run/systemd/resolve/resolv.conf", resolvConfPath)
	if err != nil {
		_ = os.Remove(resolvedConfPath) // remove the file we've just created
		return fmt.Errorf("os.Symlink: %s: %w", resolvConfPath, err)
	}

	const systemctlCmd = "systemctl"

	systemctlArgs := []string{"reload-or-restart", "systemd-resolved"}

View on GitHub (pinned to b41aefbe51)

Solutions

1. Run setup with sufficient privileges (root or sudo) so /etc/systemd/resolved.conf.d can be created
2. If systemd-resolved isn't in use, skip/disable the stub-listener step in setup
3. In containers/immutable hosts, configure the host's resolved manually or run with port 53 already free
4. Check the wrapped error for EACCES vs EROFS to confirm the cause

// Preflight: check we can create the resolved conf dir
if err := os.MkdirAll(filepath.Dir(resolvedConfPath), 0o755); err != nil {
    return fmt.Errorf("need privileges to disable DNS stub: %w", err)
}

// Skip stub-disable step when not applicable
if isMkdirErr(err) { skipStepWithWarning("run setup as root to disable systemd-resolved stub") }

When it happens

Trigger: Initial setup (validateDNS/disableDNSStubListener) on a Linux host using systemd-resolved when the process can't create the directory with mode 0755.

Common situations: Running AdGuard Home as a non-root user without sudo; immutable/read-only /etc; misconfigured containers; SELinux denying writes.

Related errors

• networksetup failed to configure dns servers: %w
• reading key file: %w
• reading db: %w
• writing new config: %w
• writing config file: %w

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