AdguardTeam/AdGuardHome · error

action

Error message

action %q: %w

What it means

A service control action selected in handleServiceControlAction (install, uninstall, start, stop, restart, status, run) returned an error, which is wrapped with the action name for context.

Solutions

1. Read the inner error — it carries the action-specific cause
2. Run with sudo for install/uninstall/start/stop/restart
3. Confirm the service is installed first: ./AdGuardHome -s status

Example fix

# before
./AdGuardHome -s install

# after
sudo ./AdGuardHome -s install

// Verify action and service presence before performing:
if !slices.Contains([]string{"install","uninstall","start","stop","restart","status"}, action) {
    return errors.New("unknown action")
}

if err := handleServiceControlAction(...); err != nil {
    // err wraps action-specific cause; branch on inner error for user guidance
    log.Fatalf("%v", err)
}

When it happens

Trigger: Any ./AdGuardHome -s <action> whose underlying handler fails — permission denied on install, unit-not-loaded on start/stop, or the 'run' path hitting cwd/service-init errors.

Common situations: Running control actions without root, operating on a service that isn't installed, or systemd refusing operations inside containers.

Related errors

• restarting service
• initializing service
• %w: %q
• applying option
• getting current directory

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

Appendix: source

Thrown at internal/home/service.go:222

			workDir:         workDir,
			confPath:        confPath,
			pidFilePath:     pidFilePath,
			hostsContainer:  hc,
		}

		return p.handleRun(ctx, baseLogger, runOpts)
	}

	switch actionName {
	case "reload":
		err = handleServiceReloadCmd(ctx, l, svcMgr)
	case "status":
		err = handleServiceStatusCmd(ctx, l, svcMgr)
	default:
		err = handleServiceCommand(ctx, baseLogger, svcMgr, opts, workDir, confPath)
	}
	if err != nil {
		return fmt.Errorf("action %q: %w", actionName, err)
	}

	return nil
}

// handleServiceCommand handles service command.
func handleServiceCommand(
	ctx context.Context,
	l *slog.Logger,
	mgr ossvc.Manager,
	opts options,
	workDir string,
	confPath string,
) (err error) {
	var action ossvc.Action
	switch opts.serviceControlAction {
	case "install":
		return handleServiceInstallCmd(ctx, l, mgr, opts, workDir, confPath)

View on GitHub (pinned to b41aefbe51)