{"record":{"id":"59a44d740991ad45","repo":"gastownhall/beads","slug":"failed-to-acquire-bootstrap-lock-w","errorCode":null,"errorMessage":"failed to acquire bootstrap lock: %w","messagePattern":"failed to acquire bootstrap lock: %w","errorType":"error_code","errorClass":null,"httpStatus":null,"severity":"error","filePath":"internal/storage/dolt/bootstrap.go","lineNumber":245,"sourceCode":"\t// #nosec G304 - controlled path\n\tf, err := os.OpenFile(lockPath, os.O_CREATE|os.O_RDWR, 0600)\n\tif err != nil {\n\t\treturn nil, fmt.Errorf(\"failed to create lock file: %w\", err)\n\t}\n\n\t// Try to acquire lock with non-blocking flock and polling.\n\tdeadline := time.Now().Add(timeout)\n\tfor {\n\t\terr := lockfile.FlockExclusiveNonBlocking(f)\n\t\tif err == nil {\n\t\t\t// Lock acquired - update modification time for stale detection\n\t\t\treturn f, nil\n\t\t}\n\n\t\tif !lockfile.IsLocked(err) {\n\t\t\t// Unexpected error (not contention)\n\t\t\t_ = f.Close() // Best effort cleanup on error path\n\t\t\treturn nil, fmt.Errorf(\"failed to acquire bootstrap lock: %w\", err)\n\t\t}\n\n\t\tif time.Now().After(deadline) {\n\t\t\t_ = f.Close() // Best effort cleanup on error path\n\t\t\treturn nil, fmt.Errorf(\"timeout after %s waiting for bootstrap lock (another bootstrap may be running)\", timeout)\n\t\t}\n\n\t\t// Wait briefly before retrying\n\t\ttime.Sleep(100 * time.Millisecond)\n\t}\n}\n\n// releaseBootstrapLock releases the bootstrap lock and removes the lock file\nfunc releaseBootstrapLock(f *os.File, lockPath string) {\n\tif f != nil {\n\t\t_ = lockfile.FlockUnlock(f) // Best effort: unlock may fail if fd is bad\n\t\t_ = f.Close()               // Best effort cleanup\n\t}","sourceCodeStart":227,"sourceCodeEnd":263,"githubUrl":"https://github.com/gastownhall/beads/blob/71377f276968b452ee607177637970a4ff888584/internal/storage/dolt/bootstrap.go#L227-L263","documentation":"While waiting to flock the bootstrap lock file, lockfile.FlockExclusiveNonBlocking returned an error that is NOT ordinary contention (lockfile.IsLocked was false). This is an unexpected flock failure, so the wait loop aborts immediately instead of polling. The file handle is closed best-effort and the OS error is wrapped.","triggerScenarios":"flock(2) fails with something other than EWOULDBLOCK: the file descriptor is invalid/closed, the filesystem does not support flock (some network mounts, some overlay/NFS setups), or the process hit a signal-interrupted syscall not handled by the lockfile helper.","commonSituations":"Running the repo on an NFS/SMB mount or a filesystem without flock support (older WSL1 setups, some Docker bind mounts); running bootstrap concurrently in a way that corrupts the descriptor; restricted seccomp/container policies blocking flock.","solutions":["Move the repository onto a local filesystem that supports flock (not NFS/SMB/network mounts)","Retry `bd bootstrap` once — transient EINTR-style failures usually clear","Inspect the wrapped `%w` error for the exact syscall errno and address that environment issue (container policy, WSL version)","Report/pin an issue if using Docker Desktop bind mounts; copy the repo into the container filesystem instead"],"exampleFix":"// before (network mount)\ncd /mnt/nfs/project && bd bootstrap\n// after (local filesystem)\ncd ~/projects/project && bd bootstrap","handlingStrategy":"retry","validationCode":"// detect flock-incompatible filesystems before bootstrap\n// Linux: statfs -f . | grep -E 'nfs|smb'  -> move repo to local disk (ext4/apfs/ntfs)","typeGuard":null,"tryCatchPattern":"if err := bd.BootstrapFromRemoteWithDB(ctx, url, target); err != nil {\n    if strings.Contains(err.Error(), \"failed to acquire bootstrap lock\") {\n        // unexpected flock failure: log wrapped cause, retry once after\n        // confirming the repo is on a flock-capable local filesystem\n    }\n}","preventionTips":["Keep the repository on a local filesystem, not NFS/SMB/network mounts","Avoid WSL1 or Docker bind mounts known to lack flock; use WSL2 or container-local storage","Check container seccomp policies permit flock syscalls","Retry transient failures once before escalating"],"tags":["flock","filesystem","lock","bootstrap"],"backgroundTag":"flock-unsupported-filesystem","analyzedSha":"71377f276968b452ee607177637970a4ff888584","analyzedAt":"2026-08-30T18:55:39.744Z","schemaVersion":2},"datasetVersion":"2026-08-30T23:17:21.991Z"}