{"record":{"id":"8d29077e84342bce","repo":"gastownhall/beads","slug":"read-backend-record-s-w","errorCode":null,"errorMessage":"read backend record %s: %w","messagePattern":"read backend record (.+?): %w","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"internal/storage/dbproxy/proxy/endpoint.go","lineNumber":779,"sourceCode":"\t\treturn fmt.Errorf(\n\t\t\t\"refusing backend cleanup: %s is held while proxy lock is free (recorded pid %d at %s); stop the process holding the child lock or remove the stale lock owner before retrying\",\n\t\t\tchildLockPath, pid, recordPath,\n\t\t)\n\tdefault:\n\t\treturn fmt.Errorf(\"probe backend lock %s: %w\", childLockPath, lockErr)\n\t}\n\n\tif readErr != nil {\n\t\tif isMalformedPIDFileError(readErr) {\n\t\t\treturn unverifiableProcessError(\n\t\t\t\t\"backend cleanup\",\n\t\t\t\trecordPath,\n\t\t\t\t0,\n\t\t\t\treadErr,\n\t\t\t\tunverifiableProcessChecks{},\n\t\t\t)\n\t\t}\n\t\treturn fmt.Errorf(\"read backend record %s: %w\", recordPath, readErr)\n\t}\n\tif pf == nil {\n\t\treturn nil\n\t}\n\tif err := pf.ValidateV2(pidfile.KindDoltBackend); err != nil {\n\t\tdead, live, probeErr := probeUnverifiablePID(pf.Pid)\n\t\tif dead {\n\t\t\tif _, quarantineErr := quarantineRecord(rootDir, server.PIDFileName, time.Now()); quarantineErr != nil {\n\t\t\t\treturn fmt.Errorf(\"quarantine dead unverifiable backend record: %w\", quarantineErr)\n\t\t\t}\n\t\t\treturn nil\n\t\t}\n\t\tif probeErr != nil {\n\t\t\terr = errors.Join(err, fmt.Errorf(\"probe recorded pid: %w\", probeErr))\n\t\t}\n\t\treturn unverifiableProcessError(\n\t\t\t\"backend cleanup\",\n\t\t\trecordPath,","sourceCodeStart":761,"sourceCodeEnd":797,"githubUrl":"https://github.com/gastownhall/beads/blob/71377f276968b452ee607177637970a4ff888584/internal/storage/dbproxy/proxy/endpoint.go#L761-L797","documentation":"cleanupOrphanBackend reads the Dolt backend PID record (pidfile) at <rootDir>/<PIDFileName> to decide whether a stale backend process must be killed. This error wraps any read failure that is NOT a malformed-record error (malformed records are routed to unverifiableProcessError instead). It signals the cleanup pass could not even inspect the record, so orphan cleanup was aborted.","triggerScenarios":"pidfile.Read returns an error other than a malformed-PID-file error: the record file exists but is unreadable (permission denied, I/O error), or an unexpected filesystem error occurs while opening/decoding it at internal/storage/dbproxy/proxy/endpoint.go:749,779.","commonSituations":"File permissions changed on the workspace .beads/dbproxy directory (e.g. record written by a different user or root); disk/IO errors; a partially-written record whose decode fails in a way not classified as malformed; running bd from a different account after a sudo invocation.","solutions":["Check permissions and ownership of the record file shown in the message and fix them (chown/chmod) so the current user can read it.","Verify the file is a valid pidfile; if it is corrupt or stale, remove or rename it (e.g. to <record>.stale-<timestamp>) and retry.","Re-run the command under the same user that created the workspace; avoid mixing sudo and non-sudo bd invocations.","If the underlying OS error persists, investigate the filesystem (disk full, mount issues) reported by the wrapped cause."],"exampleFix":"// before (record unreadable)\n$ bd doctor\nError: read backend record /ws/.beads/dbproxy/dolt-backend.pid: open ...: permission denied\n// after\n$ sudo chown $(whoami) /ws/.beads/dbproxy/dolt-backend.pid\n$ bd doctor  # cleanup proceeds","handlingStrategy":"validation","validationCode":"recordPath := filepath.Join(rootDir, \"dolt-backend.pid\")\nif _, err := os.Stat(recordPath); err != nil {\n    if errors.Is(err, fs.ErrNotExist) {\n        return nil // nothing to clean\n    }\n    return fmt.Errorf(\"record %s not readable before cleanup: %w\", recordPath, err)\n}","typeGuard":"func isMalformed(err error) bool {\n    var target *fs.PathError\n    return errors.As(err, &target) && errors.Is(target.Err, os.ErrPermission)\n}","tryCatchPattern":"if err := cleanupOrphanBackend(rootDir); err != nil {\n    var pathErr *fs.PathError\n    if errors.As(err, &pathErr) && errors.Is(pathErr.Err, os.ErrPermission) {\n        // surface guidance: fix ownership/permissions of pathErr.Path\n    }\n    return err\n}","preventionTips":["Run all bd commands as the same user that owns the workspace; avoid sudo mixing.","Check permissions on .beads/dbproxy after restoring workspaces from backups.","Monitor disk health; I/O errors surface here first.","Never hand-edit pidfile records."],"tags":["go","filesystem","pidfile","permissions"],"backgroundTag":"pidfile-read-failed","analyzedSha":"71377f276968b452ee607177637970a4ff888584","analyzedAt":"2026-08-30T18:55:39.744Z","schemaVersion":2},"datasetVersion":"2026-08-30T23:17:21.991Z"}