{"record":{"id":"85046a76520935ad","repo":"AdguardTeam/AdGuardHome","slug":"no-s-instances-found","errorCode":null,"errorMessage":"no %s instances found","messagePattern":"no (.+?) instances found","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"internal/aghos/os.go","lineNumber":102,"sourceCode":"\t\tctx,\n\t\texecutil.SystemCommandConstructor{},\n\t\t&executil.CommandConfig{\n\t\t\tPath:   psCmd,\n\t\t\tArgs:   psArgs,\n\t\t\tStdout: &stdoutBuf,\n\t\t},\n\t)\n\n\tvar instNum int\n\tpid, instNum, err = parsePSOutput(&stdoutBuf, command, except)\n\tif err != nil {\n\t\treturn 0, err\n\t}\n\n\tswitch instNum {\n\tcase 0:\n\t\t// TODO(e.burkov):  Use constant error.\n\t\treturn 0, fmt.Errorf(\"no %s instances found\", command)\n\tcase 1:\n\t\t// Go on.\n\tdefault:\n\t\tl.WarnContext(ctx, \"instances found\", \"num\", instNum, \"command\", command)\n\t}\n\n\tif runErr != nil {\n\t\tif code, ok := executil.ExitCodeFromError(runErr); ok {\n\t\t\treturn 0, fmt.Errorf(\"ps finished with code %d\", code)\n\t\t}\n\n\t\treturn 0, fmt.Errorf(\"executing the command: %w\", runErr)\n\t}\n\n\treturn pid, nil\n}\n\n// parsePSOutput scans the output of ps searching the largest PID of the process","sourceCodeStart":84,"sourceCodeEnd":120,"githubUrl":"https://github.com/AdguardTeam/AdGuardHome/blob/b41aefbe51c8dde65e2c50f093996afa0502edf9/internal/aghos/os.go#L84-L120","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Start the service/process before invoking reload, then retry","Verify the process is actually running: pgrep -f <command>","If ps behaves unusually in your environment (minimal containers), install procps or run reload outside that environment","Check that the executable name passed to PIDByCommand matches the running process name exactly"],"exampleFix":null,"handlingStrategy":"validation","validationCode":"if _, err := exec.LookPath(\"ps\"); err != nil { /* avoid reload path */ }\n// and confirm the process exists first:\n// pgrep -f <command> must return a pid","typeGuard":null,"tryCatchPattern":"pid, err := aghos.PIDByCommand(ctx, cmd)\nif err != nil && strings.Contains(err.Error(), \"no \"+cmd+\" instances found\") {\n    // process not running: start it instead of reloading\n}","preventionTips":["Ensure the service is started before triggering reload","Verify ps is installed in the runtime environment","Don't string-match; consider patching upstream to export a sentinel error"],"tags":["process","pid","ps","reload","not-found"],"backgroundTag":"process-not-found","analyzedSha":"b41aefbe51c8dde65e2c50f093996afa0502edf9","analyzedAt":"2026-08-27T04:57:55.097Z","schemaVersion":2},"datasetVersion":"2026-08-27T08:17:20.692Z"}