AdguardTeam/AdGuardHome · critical

starting service: %w

Error message

starting service: %w

What it means

Immediately after installing the service, the code sends an ActionStart to the service manager and that start operation failed. The service was registered but could not be launched, commonly because the binary, working directory, or arguments recorded in the service definition are wrong, or the start itself requires privileges that were dropped.

Source

Thrown at internal/home/service.go:342

	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)
	}

	return nil
}

View on GitHub (pinned to b41aefbe51)

Solutions

1. Check 'systemctl status AdGuardHome' / sc query output and journal logs for the start failure
2. Ensure the working directory recorded at install time still exists and is accessible
3. Uninstall and reinstall from a permanent location with correct privileges
4. Inspect SELinux/AppArmor denials if on a hardened system

// verify the recorded working directory and binary exist before start
if _, err := os.Stat(workDir); err != nil {
    log.Fatal("working directory missing: ", err)
}

When it happens

Trigger: mgr.Perform(&ossvc.ActionStart{...}) failing due to a bad WorkingDirectory (deleted between install and start), binary path resolution problems, or the service manager refusing to start without root.

Common situations: Install succeeded from a temp directory that no longer exists at start time; the binary was moved after installation; OS-level start restrictions (SELinux, AppArmor) blocking execution; partial install leaving a broken unit.

Related errors

• installing service: %w
• os.MkdirAll: %s: %w
• service manager can't reload: %w
• reloading service: %w

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