{"record":{"id":"84d919c4fb8489d7","repo":"gastownhall/beads","slug":"quarantine-orphan-backend-record-w","errorCode":null,"errorMessage":"quarantine orphan backend record: %w","messagePattern":"quarantine orphan backend record: %w","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"internal/storage/dbproxy/proxy/endpoint.go","lineNumber":849,"sourceCode":"\t\t\treturn fmt.Errorf(\"quarantine dead backend record: %w\", err)\n\t\t}\n\t\treturn nil\n\t}\n\tif err := handle.Kill(); err != nil {\n\t\t_ = handle.Close()\n\t\treturn fmt.Errorf(\"kill verified orphan backend pid %d from %s: %w\", pf.Pid, recordPath, err)\n\t}\n\t// Close before waiting: an open handle on Windows keeps the dead PID\n\t// allocated, so procid.Verify would keep matching it and the exit wait\n\t// below would always time out.\n\tif err := handle.Close(); err != nil {\n\t\treturn fmt.Errorf(\"close verified backend process handle for pid %d: %w\", pf.Pid, err)\n\t}\n\tif err := waitForRecordedProcessExit(pf, backendExitTimeout); err != nil {\n\t\treturn fmt.Errorf(\"wait for verified orphan backend pid %d: %w\", pf.Pid, err)\n\t}\n\tif _, err := quarantineRecord(rootDir, server.PIDFileName, time.Now()); err != nil {\n\t\treturn fmt.Errorf(\"quarantine orphan backend record: %w\", err)\n\t}\n\treturn nil\n}\n\ntype unverifiableProcessChecks struct {\n\tLiveEstablished bool\n\tLegacyProxy     bool\n}\n\nfunc unverifiableProcessError(\n\toperation string,\n\trecordPath string,\n\tpid int,\n\tcause error,\n\tchecks unverifiableProcessChecks,\n) error {\n\tliveness := \"\"\n\tif checks.LiveEstablished {","sourceCodeStart":831,"sourceCodeEnd":867,"githubUrl":"https://github.com/gastownhall/beads/blob/71377f276968b452ee607177637970a4ff888584/internal/storage/dbproxy/proxy/endpoint.go#L831-L867","documentation":"Final step of orphan backend cleanup: after the verified process was killed and confirmed exited, the stale PID record is quarantined (renamed into the quarantine area). This error wraps a failure of that final quarantineRecord call — the workspace is now backend-free but the stale record file remains, so cleanup reports failure.","triggerScenarios":"waitForRecordedProcessExit succeeded and quarantineRecord(rootDir, server.PIDFileName, time.Now()) fails at internal/storage/dbproxy/proxy/endpoint.go:848-849 (rename permission/IO error, target conflict).","commonSituations":"Quarantine directory not writable; filesystem full or read-only; another bd process recreated/locked the record between exit-wait and quarantine; ownership changed mid-cleanup.","solutions":["Fix permissions on the workspace and quarantine directory, then retry cleanup.","Manually rename the record: mv <recordPath> <recordPath>.stale-$(date +%s) — the backend process is already gone at this point.","Stop other concurrent bd instances that may be touching the record.","Address wrapped filesystem causes (ENOSPC/EROFS) before retrying."],"exampleFix":"// before\nError: quarantine orphan backend record: rename ...: permission denied\n// after\n$ mv /ws/.beads/dbproxy/dolt-backend.pid /ws/.beads/dbproxy/dolt-backend.pid.stale-$(date +%s)\n$ bd doctor","handlingStrategy":"fallback","validationCode":"// Verify the record is rename-able before cleanup:\nif _, err := os.Stat(recordPath); err != nil {\n    return nil // nothing to quarantine\n}\nif err := os.Chmod(recordPath, 0o644); err != nil {\n    return fmt.Errorf(\"record not quarantine-able: %w\", err)\n}","typeGuard":null,"tryCatchPattern":"if err := cleanupOrphanBackend(rootDir); err != nil && strings.Contains(err.Error(), \"quarantine orphan backend record\") {\n    // backend already killed and confirmed exited; safe to rename manually\n    os.Rename(recordPath, recordPath+\".stale-\"+strconv.FormatInt(time.Now().Unix(), 10))\n}","preventionTips":["Keep workspace and quarantine paths writable by the bd user.","Don't run concurrent bd instances against one workspace.","Preserve free disk space; quarantine renames fail on ENOSPC.","After any successful kill, the record is safe to rename manually if quarantine errors."],"tags":["go","quarantine","pidfile","filesystem"],"backgroundTag":"quarantine-rename-failed","analyzedSha":"71377f276968b452ee607177637970a4ff888584","analyzedAt":"2026-08-30T18:55:39.744Z","schemaVersion":2},"datasetVersion":"2026-08-30T23:17:21.991Z"}