What causes "setting up stealth mode: %v" in gastownhall/beads?

Read the wrapped cause and fix the underlying filesystem/permission problem

setting up stealth mode: %v

Error message

setting up stealth mode: %v

What it means

bd init with stealth mode enabled configures global stealth handling (repo mutation for stealth, global hooks). If setupStealthMode fails, init aborts with 'setting up stealth mode' wrapping the cause. Note this runs only after a destructive reinit has passed its confirmation gate.

Source

Thrown at cmd/bd/init.go:1003

		// Resolve the operational storage path only after held-gate preflight
		// succeeds. ResolveDoltDir retains its mkdir-on-use behavior for a
		// real shared-server initialization.
		initDBPath := dbPath
		if initDBPath == "" {
			initDBPath = doltserver.ResolveDoltDir(beadsDirForInit)
		}
		initDBDir := filepath.Dir(initDBPath)
		initDBDirAbs, err := filepath.Abs(initDBDir)
		if err != nil {
			initDBDirAbs = filepath.Clean(initDBDir)
		}

		// Do not mutate the repository for stealth mode until a destructive
		// reinit has passed its held-gate confirmation. Remote safety above
		// still evaluates the flag before this point.
		if stealth {
			if err := setupStealthMode(!quiet); err != nil {
				return fmt.Errorf("setting up stealth mode: %v", err)
			}

			// In stealth mode, skip git hooks installation since we handle it
			// globally.
			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 {

View on GitHub (pinned to 71377f2769)

Solutions

Read the wrapped cause and fix the underlying filesystem/permission problem
Re-run bd init --stealth after fixing
Init without --stealth first, then apply stealth configuration manually once the workspace works

Defensive patterns

Strategy: try-catch

Validate before calling

touch "$HOME/.beads-test" && rm -f "$HOME/.beads-test" || echo "home dir not writable; stealth setup will fail"

Try / catch

if err := setupStealth(); err != nil { log.Printf("stealth setup failed: %v; continuing non-stealth", err) }

Prevention

Ensure the home/global config directory is writable before --stealth init
Check for conflicting global git hooks before enabling stealth
Prefer the official release build over locally patched binaries for stealth installs

When it happens

Trigger: `bd init --stealth` where setupStealthMode fails — typically filesystem permission problems writing global stealth state, or an inability to register the global hook setup.

Common situations: Read-only home directory; conflicting existing global git hooks; corporate-managed machines blocking writes outside the repo.

Related errors

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