gastownhall/beads · error

failed to create .beads directory: %v Permission denied. Ch

Error message

failed to create .beads directory: %v

Permission denied. Check directory ownership and permissions:
  ls -la %s
  chmod 755 %s

What it means

During `bd init`, creating the `.beads/` directory failed with a permission error (os.IsPermission). On non-Windows systems bd wraps the underlying OS error with diagnostics telling the developer to inspect ownership/permissions of the parent directory and chmod 755 it.

Source

Thrown at cmd/bd/init.go:1032

		// Only skip when BEADS_DIR explicitly points outside the project.
		//
		// Previous logic only created .beads/ when the dolt data dir was a
		// subdirectory of .beads/, which broke server mode with external
		// BEADS_DOLT_DATA_DIR or BEADS_DOLT_* env vars (GH#2519).
		useLocalBeads := !hasExplicitBeadsDir || filepath.Clean(initDBDirAbs) == filepath.Clean(beadsDirAbs)

		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)
			}

View on GitHub (pinned to 71377f2769)

Solutions

1. Check ownership/permissions of the parent directory: ls -la <parent-of-.beads>
2. Fix permissions: chmod 755 <parent> or chown to the current user
3. Move to a writable directory or run init in the actual project root
4. If on a read-only mount, remount rw or copy the project to a writable location

Example fix

// before (fails)
$ cd /srv/project-owned-by-root && bd init
// after
$ sudo chown -R $USER /srv/project
$ bd init

parent=$(dirname .beads)
if [ ! -w "$parent" ]; then
  echo "Cannot write $parent — fix permissions before bd init"
  ls -la "$parent"; chmod 755 "$parent"
fi

if err := bd init; case "$?" in 0) ;; *) echo "init failed; check perms on $(pwd)" ;; esac

When it happens

Trigger: os.MkdirAll(beadsDir, ...) returns an os.IsPermission error during `bd init` on a Unix-like system; the err is syscall.EACCES/EPERM writing to the parent directory.

Common situations: Running bd init in a directory owned by another user (e.g. a checkout created by root), a read-only mount or NFS export, a project directory inside a system path like /usr, or running bd without write access after switching users or in a restricted CI container.

Related errors

• failed to create .beads directory: %w
• failed to set beads.role config: %w
• failed to create %s: %w
• failed to read %s: %w
• failed to update %s: %w

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