{"record":{"id":"6250369c7cca675b","repo":"gastownhall/beads","slug":"proxy-forcestopunverified-record-s-has-invalid-p","errorCode":null,"errorMessage":"proxy.ForceStopUnverified: record %s has invalid pid %d","messagePattern":"proxy\\.ForceStopUnverified: record (.+?) has invalid pid (.+?)","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"internal/storage/dbproxy/proxy/force_stop.go","lineNumber":191,"sourceCode":"\t\treturn nil\n\t}\n\trootID, err := identity.RootID(rootDir)\n\tif err != nil {\n\t\t// Failing open here would route a possibly-verifiable record into the\n\t\t// destructive force path; surface the identity failure instead.\n\t\treturn fmt.Errorf(\"proxy.ForceStopUnverified: resolve workspace identity: %w\", err)\n\t}\n\tif record.RootID == rootID {\n\t\treturn errors.New(\n\t\t\t\"proxy.ForceStopUnverified: record has a verifiable v2 workspace identity; use proxy.Shutdown\",\n\t\t)\n\t}\n\treturn nil\n}\n\nfunc inspectAndStopUnverifiedPID(rootDir string, pid int, deadline time.Time, report *ForceStopReport) error {\n\tif pid <= 0 {\n\t\treturn fmt.Errorf(\"proxy.ForceStopUnverified: record %s has invalid pid %d\", report.RecordPath, pid)\n\t}\n\t// One stable handle covers inspection and signaling, so the PID cannot be\n\t// recycled between the executable check and the kill on platforms with a\n\t// pinning primitive (Linux pidfd, Windows process handle).\n\tproc, gone, err := openUnverifiedProcess(pid)\n\tif err != nil {\n\t\treturn fmt.Errorf(\"proxy.ForceStopUnverified: open pid %d: %w\", pid, err)\n\t}\n\tif gone {\n\t\treport.ProcessWasGone = true\n\t\treturn nil\n\t}\n\tdefer proc.close()\n\n\texecutable, gone, err := proc.executableBasename()\n\tif err != nil {\n\t\treturn fmt.Errorf(\"proxy.ForceStopUnverified: inspect executable for pid %d: %w\", pid, err)\n\t}","sourceCodeStart":173,"sourceCodeEnd":209,"githubUrl":"https://github.com/gastownhall/beads/blob/71377f276968b452ee607177637970a4ff888584/internal/storage/dbproxy/proxy/force_stop.go#L173-L209","documentation":"inspectAndStopUnverifiedPID validates the PID from the force-stop record and rejects non-positive values because they can never name a real process. The library throws this when the record contains pid <= 0, indicating a corrupt or malformed record rather than a stoppable target.","triggerScenarios":"Calling ForceStopUnverified on a record whose decoded pid is 0 or negative — e.g. a zero-initialized or partially written PID file that still parsed.","commonSituations":"A PID file truncated to a bare '0' or '-1' after a crash, manual editing, or a tool writing placeholder values.","solutions":["Delete the malformed record file (<rootDir> PID/lock record path) and retry, since it names no real process","Verify with ps that no live proxy exists for the workspace; if none, the record is safely removable","Fix whatever wrote the placeholder PID (check for prior crash during record write)","Re-run the normal bd command to regenerate a valid record"],"exampleFix":"// before\npid := parsePid(data) // may yield 0\n_ = inspectAndStopUnverifiedPID(rootDir, pid, deadline, report)\n// after\npid := parsePid(data)\nif pid <= 0 {\n    _ = os.Remove(report.RecordPath)\n    return nil\n}\n_ = inspectAndStopUnverifiedPID(rootDir, pid, deadline, report)","handlingStrategy":"validation","validationCode":"func recordPidValid(path string) bool {\n    data, err := os.ReadFile(path)\n    if err != nil {\n        return false\n    }\n    pid, err := strconv.Atoi(strings.TrimSpace(string(data)))\n    return err == nil && pid > 0\n}","typeGuard":"func isPositivePid(n int) bool { return n > 0 }","tryCatchPattern":"report, err := proxy.ForceStopUnverified(rootDir)\nif err != nil && strings.Contains(err.Error(), \"has invalid pid\") {\n    // Record names no real process; remove it and retry\n    if rec := report.RecordPath; rec != \"\" {\n        _ = os.Remove(rec)\n        report, err = proxy.ForceStopUnverified(rootDir)\n    }\n}","preventionTips":["Treat pid<=0 records as stale and removable after confirming no live proxy","Avoid partial writes to PID files (write temp + rename)","Add checks that reject placeholder PIDs when producing records","Re-run a normal bd command to regenerate valid records"],"tags":["pidfile","validation","force-stop","corrupt-state"],"backgroundTag":"invalid-pid-in-record","analyzedSha":"71377f276968b452ee607177637970a4ff888584","analyzedAt":"2026-08-30T18:55:39.744Z","schemaVersion":2},"datasetVersion":"2026-08-30T23:17:21.991Z"}