gastownhall/beads · error

failed to create .beads directory: %v Windows Controlled Fo

Error message

failed to create .beads directory: %v

Windows Controlled Folder Access may be blocking bd.exe.
To fix: Open Windows Security > Virus & threat protection >
Ransomware protection > Allow an app through Controlled folder access
and add bd.exe (typically %USERPROFILE%\go\bin\bd.exe).

What it means

When bd init creates the local .beads directory with 0700 permissions and os.MkdirAll returns a permission error, bd gives platform-specific guidance. On Windows, the common cause is Controlled Folder Access (ransomware protection) blocking bd.exe, so the error includes step-by-step remediation.

Source

Thrown at cmd/bd/init.go:1026

			skipHooks = true
		}

		// Always create local .beads/ when using default location (CWD/.beads).
		// The local directory is needed for metadata.json, config.yaml,
		// .gitignore, and hooks — regardless of where dolt data lives.
		// 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 {

View on GitHub (pinned to 71377f2769)

Solutions

1. On Windows: add bd.exe as an allowed app via Windows Security > Ransomware protection > Controlled folder access
2. On Unix: fix permissions on the target directory (chown/chmod) or run in a writable location
3. Run from a directory your user owns, e.g. cd to the project root
4. If bd.exe is unsigned, sign it or use the released build that Windows trusts

Example fix

# before (Unix)
sudo bd init            # creates root-owned dir / permission failures
# after
cd /home/user/project && bd init

mkdir -p .beads || echo "cannot create .beads: $?)

if ! mkdir .beads 2>/dev/null; then echo "check Windows Security Controlled Folder Access for bd.exe"; fi

When it happens

Trigger: `bd init` where creating .beads fails with os.IsPermission: on Windows with Controlled Folder Access enabled, or on Unix with unwritable parent directory/root-owned paths.

Common situations: Windows Security blocking an unsigned/newly-built bd.exe; running init in a directory owned by another user; CI runners with restricted permissions.

Related errors

• failed to inspect target repo %s: %w
• dolt path is not executable
• failed to create backup directory: %w
• failed to create temp file: %w
• create beads directory: %w

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