gastownhall/beads · error

failed to create .beads directory: %v

Error message

failed to create .beads directory: %v

What it means

Generic fallback error when `bd init` fails to create the `.beads/` directory for any reason other than a permission denial (or outside the mapped cases). It surfaces the raw OS error without extra remediation hints.

Source

Thrown at cmd/bd/init.go:1038

		if useLocalBeads {
			// Create .beads directory with owner-only permissions (0700).
			if err := os.MkdirAll(beadsDir, config.BeadsDirPerm); err != nil {
				if os.IsPermission(err) {
					if runtime.GOOS == "windows" {
						return fmt.Errorf("failed to create .beads directory: %v\n\n"+
							"Windows Controlled Folder Access may be blocking bd.exe.\n"+
							"To fix: Open Windows Security > Virus & threat protection >\n"+
							"Ransomware protection > Allow an app through Controlled folder access\n"+
							"and add bd.exe (typically %%USERPROFILE%%\\go\\bin\\bd.exe).", err)
					} else {
						return fmt.Errorf("failed to create .beads directory: %v\n\n"+
							"Permission denied. Check directory ownership and permissions:\n"+
							"  ls -la %s\n"+
							"  chmod 755 %s", err, filepath.Dir(beadsDir), filepath.Dir(beadsDir))
					}
				}
				return fmt.Errorf("failed to create .beads directory: %v", err)
			}

			// Fix permissions on pre-existing .beads/ directories that may
			// have been created with a permissive umask (GH#3391).
			if fixed, err := config.FixBeadsDirPermissions(beadsDir); err != nil {
				if !quiet {
					fmt.Fprintf(os.Stderr, "Warning: could not fix .beads permissions: %v\n", err)
				}
			} else if fixed && !quiet {
				fmt.Fprintf(os.Stderr, "Fixed .beads permissions to %04o\n", config.BeadsDirPerm)
			}

			// On Linux btrfs, disable transparent compression on .beads/ so that
			// dolt's hot append-only write path (under .beads/dolt/ or
			// .beads/embeddeddolt/) does not trigger kworker thrashing from
			// read-modify-write-recompress cycles. New files created inside this
			// directory inherit FS_NOCOW_FL automatically, so setting it here —
			// before dolt writes anything — covers both server and embedded modes.

View on GitHub (pinned to 71377f2769)

Solutions

1. Read the wrapped %v OS error to identify the exact cause
2. If a file named .beads exists, remove it: rm .beads, then re-run bd init
3. Free disk space if ENOSPC (df -h)
4. Verify the path is valid and each component is a directory

Example fix

// before (fails: .beads is a file)
$ ls -la; -rw-r--r-- .beads
// after
$ rm .beads
$ bd init

if [ -e .beads ] && [ ! -d .beads ]; then
  echo ".beads exists but is not a directory"; rm -f .beads
fi
df -h . | awk 'NR==2{exit ($4+0>1024)?0:1}' || echo "low disk space"

bd init || { echo "init failed: $(cat err)"; ls -la .beads 2>/dev/null; }

When it happens

Trigger: os.MkdirAll(beadsDir, ...) returns a non-permission error (e.g. ENOSPC, ENOTDIR, EEXIST-as-file, EROFS path variants not classified as permission) during `bd init`.

Common situations: Disk full when creating .beads, a regular file named `.beads` already exists in the project, the target path component is not a directory, or a filesystem I/O error.

Related errors

• failed to create .beads directory: %v Permission denied. Ch
• failed to create storage directory %s: %v
• failed to create .beads directory: %w
• failed to search for existing databases: %w
• failed to migrate database %s to %s: %w

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