AdguardTeam/AdGuardHome · error

no %s instances found

Error message

no %s instances found

What it means

PIDByCommand runs ps to find instances of a command; if the parsed output yields zero matching processes, it returns this error meaning no running instance of the given command was found. It is a TODO-noted candidate for conversion to a constant/sentinel error, so exact string matching is brittle.

Source

Thrown at internal/aghos/os.go:102

		ctx,
		executil.SystemCommandConstructor{},
		&executil.CommandConfig{
			Path:   psCmd,
			Args:   psArgs,
			Stdout: &stdoutBuf,
		},
	)

	var instNum int
	pid, instNum, err = parsePSOutput(&stdoutBuf, command, except)
	if err != nil {
		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

View on GitHub (pinned to b41aefbe51)

Solutions

1. Start the service/process before invoking reload, then retry
2. Verify the process is actually running: pgrep -f <command>
3. If ps behaves unusually in your environment (minimal containers), install procps or run reload outside that environment
4. Check that the executable name passed to PIDByCommand matches the running process name exactly

if _, err := exec.LookPath("ps"); err != nil { /* avoid reload path */ }
// and confirm the process exists first:
// pgrep -f <command> must return a pid

pid, err := aghos.PIDByCommand(ctx, cmd)
if err != nil && strings.Contains(err.Error(), "no "+cmd+" instances found") {
    // process not running: start it instead of reloading
}

When it happens

Trigger: Calling PIDByCommand (usually from the internal service reload flow) when the target binary, e.g. AdGuardHome itself, is not currently running, or when ps output formatting on the host doesn't match what parsePSOutput expects so instNum stays 0.

Common situations: Triggering a config reload via the service subsystem when the service was never started, crashed, or was started under a different executable name; running inside containers where ps is absent or truncated.

Related errors

• ps finished with code %d
• executing the command: %w
• scanning stdout: %w
• client %q is not found
• reloading service: %w

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