{"record":{"id":"603b9538df93f8f5","repo":"gastownhall/beads","slug":"quarantine-proxy-record-w","errorCode":null,"errorMessage":"quarantine proxy record: %w","messagePattern":"quarantine proxy record: %w","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"internal/storage/dbproxy/proxy/endpoint.go","lineNumber":689,"sourceCode":"\t\t)\n\tcase adoptionUnverifiable:\n\t\tlog.Printf(\n\t\t\t\"dbproxy: proxy identity at %s could not be verified (%v); quarantining only its record under proxy.lock and starting a fresh proxy\",\n\t\t\tpidfile.Path(rootDir, PIDFileName), discovery.err,\n\t\t)\n\tcase adoptionLegacy:\n\t\tlog.Printf(\n\t\t\t\"dbproxy: quarantining legacy proxy record %s; a pre-upgrade proxy may still be running and must be stopped with the old bd binary if it does not idle-exit\",\n\t\t\tpidfile.Path(rootDir, PIDFileName),\n\t\t)\n\tcase adoptionMalformed:\n\t\tlog.Printf(\"dbproxy: quarantining malformed proxy record %s (%v) before restart\", pidfile.Path(rootDir, PIDFileName), discovery.err)\n\tdefault:\n\t\treturn fmt.Errorf(\"cannot spawn from proxy discovery status %s\", discovery.status)\n\t}\n\ttarget, err := quarantineRecord(rootDir, PIDFileName, time.Now())\n\tif err != nil {\n\t\treturn fmt.Errorf(\"quarantine proxy record: %w\", err)\n\t}\n\tlog.Printf(\"dbproxy: preserved proxy record as %s\", target)\n\treturn nil\n}\n\nfunc quarantineRecord(rootDir, name string, now time.Time) (string, error) {\n\tsource := pidfile.Path(rootDir, name)\n\tfor stamp := now.Unix(); ; stamp++ {\n\t\ttarget := filepath.Join(rootDir, name+\".stale-\"+strconv.FormatInt(stamp, 10))\n\t\tif _, err := os.Lstat(target); err == nil {\n\t\t\tcontinue\n\t\t} else if !errors.Is(err, fs.ErrNotExist) {\n\t\t\treturn \"\", fmt.Errorf(\"inspect quarantine target %s: %w\", target, err)\n\t\t}\n\t\tif err := os.Rename(source, target); err != nil {\n\t\t\treturn \"\", fmt.Errorf(\"rename %s to %s: %w\", source, target, err)\n\t\t}\n\t\treturn target, nil","sourceCodeStart":671,"sourceCodeEnd":707,"githubUrl":"https://github.com/gastownhall/beads/blob/71377f276968b452ee607177637970a4ff888584/internal/storage/dbproxy/proxy/endpoint.go#L671-L707","documentation":"quarantineForSpawn wraps failures from quarantineRecord, which renames the existing proxy pidfile to <name>.stale-<unix-ts> before spawning a fresh proxy. The rename step failed, so the stale record still blocks the workspace and the restart is aborted.","triggerScenarios":"The pidfile's containing directory is not writable, the source pidfile vanished or was replaced mid-rename, or the target stale path was created by a racing process between Lstat and Rename.","commonSituations":"Read-only workspace or NFS volume with permission issues; two bd processes racing to restart the proxy; antivirus/indexer temporarily locking the file on Windows (rename denied); disk full for metadata updates.","solutions":["Check write permission on the workspace root (the pidfile's directory) for the current user","Re-run the command — the race is transient; quarantineRecord retries with later timestamps","On Windows, exclude the workspace from AV/indexer file locking or close tools holding the pidfile open","Manually move the pidfile aside (mv <root>/.beads/proxy.pid <root>/.beads/proxy.pid.stale-manual) and retry","Check the wrapped os.Rename error (errors.Unwrap) for EXDEV/EACCES/EROFS and fix the underlying cause"],"exampleFix":"// before\ntarget, err := quarantineRecord(rootDir, PIDFileName, time.Now())\nif err != nil {\n    return fmt.Errorf(\"quarantine proxy record: %w\", err)\n}\n// after\ntarget, err := quarantineRecord(rootDir, PIDFileName, time.Now())\nif err != nil {\n    if errors.Is(err, fs.ErrPermission) {\n        log.Printf(\"workspace not writable for quarantine; retrying as %s\", os.Geteuid())\n    }\n    return fmt.Errorf(\"quarantine proxy record: %w\", err)\n}","handlingStrategy":"retry","validationCode":"if fi, err := os.Stat(pidfile.Path(root, PIDFileName)); err == nil && !fi.Mode().IsRegular() {\n    return fmt.Errorf(\"proxy pidfile %s is not a regular file\", pidfile.Path(root, PIDFileName))\n}\nif f, err := os.OpenFile(root, os.O_WRONLY, 0); err != nil {\n    return fmt.Errorf(\"workspace root not writable: %w\", err)\n} else { f.Close() }","typeGuard":null,"tryCatchPattern":"err := quarantineForSpawn(root, discovery)\nfor i := 0; err != nil && strings.Contains(err.Error(), \"quarantine proxy record\") && i < 2; i++ {\n    time.Sleep(100 * time.Millisecond)\n    err = quarantineForSpawn(root, discovery)\n}","preventionTips":["Ensure workspace directories are writable by the running user before starting bd","Exclude the workspace from AV/indexer real-time locking on Windows","Serialize bd invocations per workspace so two processes don't race the quarantine rename","Keep the workspace on a single local filesystem (avoid NFS rename quirks)"],"tags":["pidfile","filesystem","rename"],"backgroundTag":"file-rename-failed","analyzedSha":"71377f276968b452ee607177637970a4ff888584","analyzedAt":"2026-08-30T18:55:39.744Z","schemaVersion":2},"datasetVersion":"2026-08-30T23:17:21.991Z"}