{"record":{"id":"4049c770196355aa","repo":"gastownhall/beads","slug":"s-env-var-is-not-supported-and-has-been-removed-t","errorCode":null,"errorMessage":"%s env var is not supported and has been removed to prevent data fragmentation.\nUnset %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","messagePattern":"(.+?) env var is not supported and has been removed to prevent data fragmentation\\.\nUnset (.+?); 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","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"cmd/bd/main.go","lineNumber":2061,"sourceCode":"\t}\n\tswitch cmd.Name() {\n\tcase \"prune\", \"purge\":\n\t\treturn commandMayEmptyJSONLExport.Load()\n\tdefault:\n\t\treturn false\n\t}\n}\n\n// blockedEnvVars lists environment variables that must not be set because they\n// could silently override the storage backend via viper's AutomaticEnv, causing\n// data fragmentation (bd-hevyw).\nvar blockedEnvVars = []string{\"BD_BACKEND\", \"BD_DATABASE_BACKEND\"}\n\n// checkBlockedEnvVars returns an error if any blocked env vars are set.\nfunc checkBlockedEnvVars() error {\n\tfor _, name := range blockedEnvVars {\n\t\tif os.Getenv(name) != \"\" {\n\t\t\treturn fmt.Errorf(\"%s env var is not supported and has been removed to prevent data fragmentation.\\n\"+\n\t\t\t\t\"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)\n\t\t}\n\t}\n\treturn nil\n}\n\n// setupGracefulShutdown creates a context that cancels on SIGINT/SIGTERM/SIGHUP.\n// Before cancellation, it flushes pending batch commits so that accumulated\n// changes in the Dolt working set are not lost on graceful shutdown.\nfunc setupGracefulShutdown() (context.Context, context.CancelFunc) {\n\tctx, cancel := context.WithCancel(context.Background()) //nolint:gosec // G118: cancel is returned and called by caller\n\n\tsigCh := make(chan os.Signal, 1)\n\tsignal.Notify(sigCh, os.Interrupt, syscall.SIGTERM, syscall.SIGHUP)\n\n\tgo func() {\n\t\tselect {\n\t\tcase <-sigCh:","sourceCodeStart":2043,"sourceCodeEnd":2079,"githubUrl":"https://github.com/gastownhall/beads/blob/71377f276968b452ee607177637970a4ff888584/cmd/bd/main.go#L2043-L2079","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","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"],"exampleFix":"# before\nexport BD_BACKEND=dolt\nbd list\n# after\nunset BD_BACKEND\nbd list   # backend comes from .beads/metadata.json","handlingStrategy":"validation","validationCode":"for _, v := range []string{\"BD_BACKEND\", \"BD_DATABASE_BACKEND\"} {\n\tif os.Getenv(v) != \"\" {\n\t\treturn fmt.Errorf(\"unset %s before running bd\", v)\n\t}\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["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"],"tags":["cli","environment","configuration","removed-feature"],"backgroundTag":"blocked-env-var","analyzedSha":"71377f276968b452ee607177637970a4ff888584","analyzedAt":"2026-08-30T18:55:39.744Z","schemaVersion":2},"datasetVersion":"2026-08-30T23:17:21.991Z"}