{"record":{"id":"1f2b95cfc543d5f0","repo":"gastownhall/beads","slug":"database-is-not-initialized-run-bd-init-first","errorCode":null,"errorMessage":"database is not initialized. Run 'bd init' first","messagePattern":"database is not initialized\\. Run 'bd init' first","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"cmd/bd/backup_restore.go","lineNumber":84,"sourceCode":"\t\t}\n\n\t\tif !jsonOutput {\n\t\t\tfmt.Printf(\"%s Restore complete\\n\", ui.RenderPass(\"✓\"))\n\t\t}\n\n\t\treturn nil\n\t},\n}\n\nfunc init() {\n\tbackupRestoreCmd.Flags().Bool(\"force\", false, \"Overwrite existing database with backup contents\")\n\tbackupCmd.AddCommand(backupRestoreCmd)\n}\n\n// runBackupRestore restores the database from a Dolt-native backup.\nfunc runBackupRestore(ctx context.Context, s storage.DoltStorage, dir string, force bool) error {\n\tif s == nil {\n\t\treturn fmt.Errorf(\"database is not initialized. Run 'bd init' first\")\n\t}\n\n\tbs, ok := storage.UnwrapStore(s).(storage.BackupStore)\n\tif !ok {\n\t\treturn fmt.Errorf(\"storage backend does not support backup operations\")\n\t}\n\n\tif err := bs.RestoreDatabase(ctx, dir, force); err != nil {\n\t\treturn err\n\t}\n\n\t// After a force restore, the database's _project_id may differ from\n\t// metadata.json (the backup came from a different project). Sync\n\t// metadata.json to match the restored database so the identity check\n\t// doesn't reject subsequent connections.\n\tif force {\n\t\tif err := syncProjectIDFromDB(ctx, s); err != nil {\n\t\t\tfmt.Fprintf(os.Stderr, \"Warning: failed to sync project ID after restore: %v\\n\", err)","sourceCodeStart":66,"sourceCodeEnd":102,"githubUrl":"https://github.com/gastownhall/beads/blob/71377f276968b452ee607177637970a4ff888584/cmd/bd/backup_restore.go#L66-L102","documentation":"runBackupRestore requires a live DoltStorage handle (s). If the storage handle is nil, there is no open database to restore into, so the command fails fast telling the user to initialize the workspace with 'bd init'. It is a guard against restoring into a non-existent database.","triggerScenarios":"Executing 'bd backup restore' in a directory where no beads database has been initialized — s (the DoltStorage) is nil because 'bd init' was never run or the current directory is outside a beads workspace.","commonSituations":"Running restore in a fresh clone before 'bd init'; running from the wrong directory (not the project root with .beads); deleted .beads directory; scripting restore into a brand-new environment.","solutions":["Run 'bd init' in the project directory to create the database, then retry the restore","cd into the correct project root that contains the .beads directory","If intentionally restoring into a fresh location, initialize first (restore overwrites the DB contents afterwards)"],"exampleFix":"// before\nbd backup restore /path/to/backup\n// after\nbd init\nbd backup restore /path/to/backup","handlingStrategy":"validation","validationCode":"if _, err := os.Stat(filepath.Join(dir, \".beads\")); os.IsNotExist(err) {\n\treturn fmt.Errorf(\"not a beads workspace; run 'bd init' first\")\n}","typeGuard":"s != nil","tryCatchPattern":"if err := runBackupRestore(ctx, s, dir, force); err != nil {\n\tif strings.Contains(err.Error(), \"not initialized\") {\n\t\t// run bd init then retry\n\t}\n\treturn err\n}","preventionTips":["Run 'bd init' before any database command in a new clone or machine","In scripts, check for the .beads directory before invoking bd commands","Run restore from the project root, not a subdirectory or scratch dir","Document bootstrap order: bd init -> bd backup restore -> bd sync"],"tags":["init","backup","restore","go"],"backgroundTag":"database-not-initialized","analyzedSha":"71377f276968b452ee607177637970a4ff888584","analyzedAt":"2026-08-30T18:55:39.744Z","schemaVersion":2},"datasetVersion":"2026-08-30T23:17:21.991Z"}