gastownhall/beads · error

failed to acquire bootstrap lock: %w

Error message

failed to acquire bootstrap lock: %w

What it means

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.

Source

Thrown at internal/storage/dolt/bootstrap.go:245

	// #nosec G304 - controlled path
	f, err := os.OpenFile(lockPath, os.O_CREATE|os.O_RDWR, 0600)
	if err != nil {
		return nil, fmt.Errorf("failed to create lock file: %w", err)
	}

	// Try to acquire lock with non-blocking flock and polling.
	deadline := time.Now().Add(timeout)
	for {
		err := lockfile.FlockExclusiveNonBlocking(f)
		if err == nil {
			// Lock acquired - update modification time for stale detection
			return f, nil
		}

		if !lockfile.IsLocked(err) {
			// Unexpected error (not contention)
			_ = f.Close() // Best effort cleanup on error path
			return nil, fmt.Errorf("failed to acquire bootstrap lock: %w", err)
		}

		if time.Now().After(deadline) {
			_ = f.Close() // Best effort cleanup on error path
			return nil, fmt.Errorf("timeout after %s waiting for bootstrap lock (another bootstrap may be running)", timeout)
		}

		// Wait briefly before retrying
		time.Sleep(100 * time.Millisecond)
	}
}

// releaseBootstrapLock releases the bootstrap lock and removes the lock file
func releaseBootstrapLock(f *os.File, lockPath string) {
	if f != nil {
		_ = lockfile.FlockUnlock(f) // Best effort: unlock may fail if fd is bad
		_ = f.Close()               // Best effort cleanup
	}

View on GitHub (pinned to 71377f2769)

Solutions

1. Move the repository onto a local filesystem that supports flock (not NFS/SMB/network mounts)
2. Retry `bd bootstrap` once — transient EINTR-style failures usually clear
3. Inspect the wrapped `%w` error for the exact syscall errno and address that environment issue (container policy, WSL version)
4. Report/pin an issue if using Docker Desktop bind mounts; copy the repo into the container filesystem instead

Example fix

// before (network mount)
cd /mnt/nfs/project && bd bootstrap
// after (local filesystem)
cd ~/projects/project && bd bootstrap

// detect flock-incompatible filesystems before bootstrap
// Linux: statfs -f . | grep -E 'nfs|smb'  -> move repo to local disk (ext4/apfs/ntfs)

if err := bd.BootstrapFromRemoteWithDB(ctx, url, target); err != nil {
    if strings.Contains(err.Error(), "failed to acquire bootstrap lock") {
        // unexpected flock failure: log wrapped cause, retry once after
        // confirming the repo is on a flock-capable local filesystem
    }
}

When it happens

Trigger: 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.

Common situations: 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.

Related errors

• create beads directory: %w
• write metadata.json: %w
• create config.yaml: %w
• probe proxy lock: %w
• failed to create dolt directory: %w

AI-assisted analysis of gastownhall/beads@71377f2769 (2026-08-30). Data as JSON: /api/errors/59a44d740991ad45. Report an issue: GitHub.