{"record":{"id":"934c1ecd2fa682b9","repo":"gastownhall/beads","slug":"probe-backend-lock-s-w","errorCode":null,"errorMessage":"probe backend lock %s: %w","messagePattern":"probe backend lock (.+?): %w","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"internal/storage/dbproxy/proxy/endpoint.go","lineNumber":766,"sourceCode":"\trecordPath := pidfile.Path(rootDir, server.PIDFileName)\n\tpf, readErr := pidfile.Read(rootDir, server.PIDFileName)\n\n\tchildLockPath := filepath.Join(rootDir, server.LockFileName)\n\tchildLock, lockErr := util.TryLock(childLockPath)\n\tswitch {\n\tcase lockErr == nil:\n\t\tchildLock.Unlock()\n\tcase lockfile.IsLocked(lockErr):\n\t\tpid := 0\n\t\tif pf != nil {\n\t\t\tpid = pf.Pid\n\t\t}\n\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 {","sourceCodeStart":748,"sourceCodeEnd":784,"githubUrl":"https://github.com/gastownhall/beads/blob/71377f276968b452ee607177637970a4ff888584/internal/storage/dbproxy/proxy/endpoint.go#L748-L784","documentation":"cleanupOrphanBackend wraps unexpected errors from util.TryLock on the backend child lock file. This is neither success nor a clean 'locked' answer, so the probe itself failed and backend cleanup cannot safely proceed.","triggerScenarios":"util.TryLock(childLockPath) returns an OS error other than EWOULDBLOCK-style 'is locked' — e.g. permission denied opening/creating the lock file, or path errors (component is not a directory, I/O error on the workspace).","commonSituations":"The lock file path exists as a directory or is otherwise unwritable; workspace mounted read-only or on a filesystem without flock support (some network FS); permission mismatch after running bd as different users (root-owned lock file).","solutions":["Inspect the wrapped OS error (errors.Unwrap) — it names the failing syscall on the lock path","Fix permissions/ownership of the lock file and its directory (chown/chmod, remove a root-owned server.lock if appropriate)","Verify the workspace is on a filesystem supporting flock (avoid NFS without local locking; move workspace to local disk)","Confirm the lock path is a regular file (rm a wrongly-typed directory entry named like the lock) and re-run"],"exampleFix":"// before\nchildLock, lockErr := util.TryLock(childLockPath)\n...\ndefault:\n    return fmt.Errorf(\"probe backend lock %s: %w\", childLockPath, lockErr)\n// after (caller)\nif err := cleanupOrphanBackend(root); err != nil && strings.HasPrefix(err.Error(), \"probe backend lock\") {\n    st, statErr := os.Stat(childLockPath)\n    fmt.Printf(\"lock probe failed: %v (path stat: %v, %v)\\n\", err, statErr, st)\n}","handlingStrategy":"validation","validationCode":"lp := root + \"/.beads/server.lock\"\nif fi, err := os.Stat(lp); err != nil {\n    if !errors.Is(err, fs.ErrNotExist) {\n        return fmt.Errorf(\"lock path unusable: %w\", err)\n    }\n} else if !fi.Mode().IsRegular() {\n    return fmt.Errorf(\"%s is not a regular file\", lp)\n}\nif f, err := os.OpenFile(lp, os.O_RDWR|os.O_CREATE, 0o600); err != nil {\n    return fmt.Errorf(\"cannot open lock file: %w\", err)\n} else { f.Close() }","typeGuard":null,"tryCatchPattern":"err := cleanupOrphanBackend(root)\nif err != nil && strings.HasPrefix(err.Error(), \"probe backend lock \") {\n    // wrapped OS error names the failing syscall: fix perms/filesystem, then retry\n}","preventionTips":["Keep the workspace on a local filesystem with working flock (not bare NFS)","Maintain consistent ownership/permissions on .beads across all bd users","Ensure lock files are regular files, not directories or symlinks","Check disk and mount health when lock acquisition starts failing"],"tags":["file-lock","filesystem","permissions"],"backgroundTag":"file-lock-acquire-failed","analyzedSha":"71377f276968b452ee607177637970a4ff888584","analyzedAt":"2026-08-30T18:55:39.744Z","schemaVersion":2},"datasetVersion":"2026-08-30T23:17:21.991Z"}