{"record":{"id":"68aaba5862458d54","repo":"gastownhall/beads","slug":"clearing-lock-metadata-w","errorCode":null,"errorMessage":"clearing lock metadata: %w","messagePattern":"clearing lock metadata: %w","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"warning","filePath":"internal/linear/synclock.go","lineNumber":90,"sourceCode":"}\n\n// Release releases the sync lock. The kernel-lock file is NOT removed — doing\n// so after unlocking creates a race where a blocked waiter acquires the old\n// inode while a new process creates a fresh file at the same path, splitting\n// lock identity. On Unix, inline owner metadata is truncated while still\n// holding the lock. On Windows, a separate advisory record is cleared while\n// still holding the authoritative guard.\nfunc (l *SyncLock) Release() error {\n\tif l == nil || l.file == nil {\n\t\treturn nil\n\t}\n\n\t// Clear or invalidate diagnostic metadata before releasing the authoritative\n\t// lock. Platform helpers preserve Unix errors and make Windows diagnostics\n\t// best-effort.\n\tvar metadataErr error\n\tif err := clearSyncLockInfo(l.file, l.infoPath, &l.metadata); err != nil {\n\t\tmetadataErr = fmt.Errorf(\"clearing lock metadata: %w\", err)\n\t}\n\n\tunlockErr := lockfile.FlockUnlock(l.file)\n\tcloseErr := l.file.Close()\n\tl.file = nil\n\n\tif unlockErr != nil {\n\t\treturn unlockErr\n\t}\n\tif closeErr != nil {\n\t\treturn closeErr\n\t}\n\treturn metadataErr\n}\n\n// SyncLockHeldError is returned when the lock is held by another process.\ntype SyncLockHeldError struct {\n\tInfo *SyncLockInfo","sourceCodeStart":72,"sourceCodeEnd":108,"githubUrl":"https://github.com/gastownhall/beads/blob/71377f276968b452ee607177637970a4ff888584/internal/linear/synclock.go#L72-L108","documentation":"SyncLock.Release first clears or invalidates the advisory metadata (owner info) while still holding the kernel lock, then unlocks and closes the file. If clearSyncLockInfo fails, the error is captured and returned (after unlock/close succeed) wrapped as this message. The authoritative lock IS still released; only the diagnostics cleanup failed.","triggerScenarios":"Calling Release when clearSyncLockInfo cannot truncate the inline owner metadata (Unix) or clear the advisory record (Windows) — e.g. I/O error on the lock file, read-only remount mid-session, or Windows file-handle contention.","commonSituations":"Disk full at release time; filesystem remounted read-only; lock file deleted underneath the holder by a cleanup script; antivirus briefly locking the metadata file on Windows.","solutions":["Treat as mostly benign: verify the kernel lock was released (unlock/close errors are returned first) before panicking","Free disk space or fix filesystem permissions if the wrapped error is I/O or permission related","Stop cleanup scripts from deleting files in the beads directory while syncs run","Manually remove stale .linear-sync.lock metadata when no sync is running"],"exampleFix":"// before: failing hard on metadata cleanup\nif err := lock.Release(); err != nil { return err }\n// after: only fail on real unlock problems; log metadata issues\nif err := lock.Release(); err != nil {\n    if strings.Contains(err.Error(), \"clearing lock metadata\") {\n        log.Warnf(\"lock metadata cleanup failed: %v\", err)\n        return nil\n    }\n    return err\n}","handlingStrategy":"try-catch","validationCode":null,"typeGuard":null,"tryCatchPattern":"if err := lock.Release(); err != nil {\n    if strings.Contains(err.Error(), \"clearing lock metadata\") {\n        log.Warnf(\"non-fatal: lock metadata cleanup failed: %v\", err)\n        return nil // kernel lock was still released\n    }\n    return err // real unlock/close failure\n}","preventionTips":["Treat metadata-cleanup failures as warnings; only unlock/close failures are fatal","Maintain free disk space so truncating metadata at release never fails","Avoid external processes deleting or locking files in the beads directory","Always pair AcquireSyncLock with a deferred Release"],"tags":["file-lock","filesystem","cleanup","go"],"backgroundTag":"file-lock-release-cleanup-failed","analyzedSha":"71377f276968b452ee607177637970a4ff888584","analyzedAt":"2026-08-30T18:55:39.744Z","schemaVersion":2},"datasetVersion":"2026-08-30T23:17:21.991Z"}