%s env var is not supported and has been removed to prevent

Error message

%s env var is not supported and has been removed to prevent data fragmentation.
Unset %s; storage selection comes from .beads/metadata.json. To choose a different supported backend, follow 'bd help init-safety'; do not edit metadata.json by hand

What it means

bd removed the BD_BACKEND / BD_DATABASE_BACKEND environment variables because per-invocation backend selection caused data fragmentation across incompatible storage files. Startup checks these env vars and refuses to run if any is set, telling the user that storage selection now lives exclusively in .beads/metadata.json.

Source

Thrown at cmd/bd/main.go:2061

	}
	switch cmd.Name() {
	case "prune", "purge":
		return commandMayEmptyJSONLExport.Load()
	default:
		return false
	}
}

// blockedEnvVars lists environment variables that must not be set because they
// could silently override the storage backend via viper's AutomaticEnv, causing
// data fragmentation (bd-hevyw).
var blockedEnvVars = []string{"BD_BACKEND", "BD_DATABASE_BACKEND"}

// checkBlockedEnvVars returns an error if any blocked env vars are set.
func checkBlockedEnvVars() error {
	for _, name := range blockedEnvVars {
		if os.Getenv(name) != "" {
			return fmt.Errorf("%s env var is not supported and has been removed to prevent data fragmentation.\n"+
				"Unset %s; storage selection comes from .beads/metadata.json. To choose a different supported backend, follow 'bd help init-safety'; do not edit metadata.json by hand", name, name)
		}
	}
	return nil
}

// setupGracefulShutdown creates a context that cancels on SIGINT/SIGTERM/SIGHUP.
// Before cancellation, it flushes pending batch commits so that accumulated
// changes in the Dolt working set are not lost on graceful shutdown.
func setupGracefulShutdown() (context.Context, context.CancelFunc) {
	ctx, cancel := context.WithCancel(context.Background()) //nolint:gosec // G118: cancel is returned and called by caller

	sigCh := make(chan os.Signal, 1)
	signal.Notify(sigCh, os.Interrupt, syscall.SIGTERM, syscall.SIGHUP)

	go func() {
		select {
		case <-sigCh:

View on GitHub (pinned to 71377f2769)

Solutions

Unset the variable in the current shell: `unset BD_BACKEND BD_DATABASE_BACKEND`
Remove the export from shell startup files (~/.bashrc, ~/.zshrc, .envrc) or CI config
To change backends, follow `bd help init-safety` and let bd manage .beads/metadata.json — do not hand-edit it

Example fix

# before
export BD_BACKEND=dolt
bd list
# after
unset BD_BACKEND
bd list   # backend comes from .beads/metadata.json

Defensive patterns

Strategy: validation

Validate before calling

for _, v := range []string{"BD_BACKEND", "BD_DATABASE_BACKEND"} {
	if os.Getenv(v) != "" {
		return fmt.Errorf("unset %s before running bd", v)
	}
}

Prevention

Remove BD_BACKEND/BD_DATABASE_BACKEND from all shell rc files and CI env
Use `bd help init-safety` workflows instead of env-based backend selection
Never hand-edit .beads/metadata.json

When it happens

Trigger: BD_BACKEND or BD_DATABASE_BACKEND is set (to any non-empty value) in the shell environment when any `bd` command starts and checkBlockedEnvVars runs.

Common situations: Stale exports in ~/.bashrc, ~/.zshrc or CI workflow env from an older bd version; wrapper scripts or Makefiles exporting the var; direnv files carrying legacy config after upgrading bd.

Related errors

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