AdguardTeam/AdGuardHome · error

action %q: %w

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.

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)

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: %w
• initializing service: %w
• %w: %q
• parsing port: %w
• parsing arg at index %d: %w

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