gastownhall/beads · error

failed to create storage directory %s: %v

Error message

failed to create storage directory %s: %v

What it means

In Dolt server mode, `bd init` explicitly creates the storage directory (initDBPath) with os.MkdirAll because the server-mode client connects over TCP and does not create local directories itself. Failure to create it aborts initialization.

Source

Thrown at cmd/bd/init.go:1127

			if output, err := gitInitCmd.CombinedOutput(); err != nil {
				return fmt.Errorf("failed to initialize git repository: %v\n%s", err, output)
			}
			// Clear cached git context so subsequent operations (e.g. hook
			// installation) see the newly-created repository (GH#2899).
			git.ResetCaches()
			if !quiet {
				fmt.Printf("  %s Initialized git repository\n", ui.RenderPass("✓"))
			}
		}

		// Ensure storage directory exists (.beads/dolt).
		// In server mode, dolt.New() connects via TCP and doesn't create local directories,
		// so we create the marker directory explicitly.
		// In embedded mode the engine creates its own directories under .beads/embeddeddolt/,
		// so skip this to avoid leaving an empty .beads/dolt/ artifact (GH#2903).
		if initServerMode {
			if err := os.MkdirAll(initDBPath, config.BeadsDirPerm); err != nil {
				return fmt.Errorf("failed to create storage directory %s: %v", initDBPath, err)
			}
			// Linux btrfs: disable compression on the dolt data dir to avoid
			// kworker thrashing on the append-only write path. Best-effort; a
			// non-btrfs filesystem returns nil from applyNoCOW.
			if err := applyNoCOW(initDBPath); err != nil && !quiet {
				fmt.Fprintf(os.Stderr, "Warning: failed to set FS_NOCOW_FL on %s: %v\n", initDBPath, err)
			}
		}

		ctx := rootCtx

		// Create Dolt storage backend
		storagePath := doltserver.ResolveDoltDir(beadsDir)
		// Respect existing config's database name to avoid creating phantom catalog
		// entries when a user has renamed their database (GH#2051).
		dbName := ""
		if existingCfg, _ := configfile.Load(beadsDir); existingCfg != nil && existingCfg.DoltDatabase != "" {
			dbName = existingCfg.DoltDatabase

View on GitHub (pinned to 71377f2769)

Solutions

1. Inspect the wrapped %v error and the target path; check permissions: ls -la .beads
2. chmod/chown .beads so the current user can create subdirectories
3. Remove any file blocking the path (e.g. a regular file named dolt)
4. Free disk space or remount rw if ENOSPC/EROFS

Example fix

// before (fails: .beads owned by root)
$ bd init --server ...
// after
$ sudo chown -R $USER .beads
$ bd init --server ...

if [ -e .beads/dolt ] && [ ! -d .beads/dolt ]; then rm -f .beads/dolt; fi
[ -w .beads ] || { echo ".beads not writable"; chown -R "$USER" .beads; }

bd init --server ... || { rc=$?; ls -la .beads; exit $rc; }

When it happens

Trigger: os.MkdirAll(initDBPath, config.BeadsDirPerm) fails during `bd init` while initServerMode is enabled (e.g. BEADS_DOLT_SERVER or --shared-server style configuration).

Common situations: Permission problems inside .beads, a read-only filesystem, disk full, or .beads/dolt existing as a regular file; also occurs when the earlier .beads dir was created by another user (root) in Docker.

Related errors

• multiple .doltcfg directories detected
• dolt path is not executable
• resolve proxied server root: %w
• creating .bd-dolt-ok marker: %w
• failed to remove Dolt database: %w

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