What causes "executing the command: %w" in AdguardTeam/AdGuardHome?

Inspect the wrapped error with errors.Unwrap to distinguish not-found vs signal vs context.Canceled

executing the command: %w

Error message

executing the command: %w

What it means

Generic wrapper returned by PIDByCommand when running the ps command fails without a recognizable exit code — i.e. the error couldn't be spawn-related exit status (couldn't start, was killed by signal, or context canceled). The %w preserves the underlying exec error for inspection.

Source

Thrown at internal/aghos/os.go:114

		return 0, err
	}

	switch instNum {
	case 0:
		// TODO(e.burkov):  Use constant error.
		return 0, fmt.Errorf("no %s instances found", command)
	case 1:
		// Go on.
	default:
		l.WarnContext(ctx, "instances found", "num", instNum, "command", command)
	}

	if runErr != nil {
		if code, ok := executil.ExitCodeFromError(runErr); ok {
			return 0, fmt.Errorf("ps finished with code %d", code)
		}

		return 0, fmt.Errorf("executing the command: %w", runErr)
	}

	return pid, nil
}

// parsePSOutput scans the output of ps searching the largest PID of the process
// associated with cmdName ignoring PIDs from ignore.  A valid line from r
// should look like these:
//
//	 123 ./example-cmd
//	1230 some/base/path/example-cmd
//	3210 example-cmd
func parsePSOutput(r io.Reader, cmdName string, ignore []int) (largest, instNum int, err error) {
	s := bufio.NewScanner(r)
	for s.Scan() {
		fields := strings.Fields(s.Text())
		if len(fields) != 2 || path.Base(fields[1]) != cmdName {
			continue

View on GitHub (pinned to b41aefbe51)

Solutions

Inspect the wrapped error with errors.Unwrap to distinguish not-found vs signal vs context.Canceled
Ensure ps exists and is executable in the service's environment (check PATH and systemd restrictions)
Increase or remove the timeout on the context passed to PIDByCommand if it's expiring early

Example fix

// before
pid, err := aghos.PIDByCommand(ctx, cmd)

// after
pid, err := aghos.PIDByCommand(ctx, cmd)
if err != nil {
    if errors.Is(err, context.Canceled) { return }
    if errors.Is(err, exec.ErrNotFound) { /* install ps */ }
}

Defensive patterns

Strategy: try-catch

Try / catch

if err != nil {
    if errors.Is(err, context.Canceled) || errors.Is(err, context.DeadlineExceeded) { return }
    if errors.Is(err, exec.ErrNotFound) { /* install ps */ }
    return err // other exec failure
}

Prevention

Pass a context with adequate timeout
Ensure PATH includes the directory containing ps in service environments
Unwrap and classify the underlying error before retrying

When it happens

Trigger: exec.CommandContext fails to start ps (binary not found, PATH issues), the command is killed by a signal (no exit code), or the context passed to PIDByCommand is canceled/expired before ps completes.

Common situations: Canceled shutdown contexts during reload; PATH missing /bin/ps in systemd hardening (NoNewPrivileges/RestrictCommands); ps terminated by a supervisor timeout.

Related errors

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