AdguardTeam/AdGuardHome · critical

installing service: %w

Error message

installing service: %w

What it means

mgr.Install returned an error while registering AdGuard Home as an OS service. The wrapped error comes from the platform service layer (e.g. systemd unit write, sc.exe create, launchd plist install) and typically indicates privilege or filesystem problems.

Source

Thrown at internal/home/service.go:335

		return fmt.Errorf("getting current directory: %w", err)
	}

	runOpts := opts
	runOpts.serviceControlAction = "run"

	args := optsToArgs(runOpts)
	l.DebugContext(ctx, "using", "args", args)

	err = mgr.Perform(ctx, &ossvc.ActionInstall{
		ServiceName:      serviceName,
		DisplayName:      serviceDisplayName,
		Description:      serviceDescription,
		WorkingDirectory: pwd,
		Version:          version.Full(),
		Arguments:        args,
	})
	if err != nil {
		return fmt.Errorf("installing service: %w", err)
	}

	err = mgr.Perform(ctx, &ossvc.ActionStart{
		ServiceName: serviceName,
	})
	if err != nil {
		return fmt.Errorf("starting service: %w", err)
	}

	if detectFirstRun(ctx, l, workDir, confPath) {
		slogutil.PrintLines(ctx, l, slog.LevelInfo, "", "Almost ready!\n"+
			"AdGuard Home is successfully installed and will automatically start on boot.\n"+
			"There are a few more things that must be configured before you can use it.\n"+
			"Click on the link below and follow the Installation Wizard steps to finish setup.\n"+
			"AdGuard Home is now available at the following addresses:")
		printHTTPAddresses(ctx, l)
	}

View on GitHub (pinned to b41aefbe51)

Solutions

1. Re-run with elevated privileges (sudo / admin shell)
2. Remove or stop the pre-existing conflicting service first ('AdGuardHome -s uninstall' or systemctl delete the unit)
3. Verify the platform actually has a supported service manager (systemd, launchd, Windows SCM)
4. Check filesystem writability of the service definition location

// pre-flight: can we write the service definition location?
if info, err := os.Stat("/etc/systemd/system"); err != nil || !info.IsDir() {
    log.Fatal("systemd not available")
}

// after
err := handleServiceInstallCmd(...)
if err != nil && strings.Contains(err.Error(), "installing service") {
    // inspect inner error, likely EPERM/EEXIST
}

When it happens

Trigger: Running 'AdGuardHome -s install' without root/administrator rights; a service with the same name already existing; inability to write the unit file/plist/registry entry; unsupported init system on Linux.

Common situations: Plain user shell instead of sudo; leftover AdGuardHome service from a previous install; read-only /etc or /Library/LaunchDaemons; running inside a container without an init system.

Related errors

• reloading service: %w
• starting service: %w
• setting gid: %w
• setting uid: %w
• os.MkdirAll: %s: %w

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