gastownhall/beads · error

database is not initialized. Run 'bd init' first

Error message

database is not initialized. Run 'bd init' first

What it means

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.

Source

Thrown at cmd/bd/backup_restore.go:84

		}

		if !jsonOutput {
			fmt.Printf("%s Restore complete\n", ui.RenderPass("✓"))
		}

		return nil
	},
}

func init() {
	backupRestoreCmd.Flags().Bool("force", false, "Overwrite existing database with backup contents")
	backupCmd.AddCommand(backupRestoreCmd)
}

// runBackupRestore restores the database from a Dolt-native backup.
func runBackupRestore(ctx context.Context, s storage.DoltStorage, dir string, force bool) error {
	if s == nil {
		return fmt.Errorf("database is not initialized. Run 'bd init' first")
	}

	bs, ok := storage.UnwrapStore(s).(storage.BackupStore)
	if !ok {
		return fmt.Errorf("storage backend does not support backup operations")
	}

	if err := bs.RestoreDatabase(ctx, dir, force); err != nil {
		return err
	}

	// After a force restore, the database's _project_id may differ from
	// metadata.json (the backup came from a different project). Sync
	// metadata.json to match the restored database so the identity check
	// doesn't reject subsequent connections.
	if force {
		if err := syncProjectIDFromDB(ctx, s); err != nil {
			fmt.Fprintf(os.Stderr, "Warning: failed to sync project ID after restore: %v\n", err)

View on GitHub (pinned to 71377f2769)

Solutions

1. Run 'bd init' in the project directory to create the database, then retry the restore
2. cd into the correct project root that contains the .beads directory
3. If intentionally restoring into a fresh location, initialize first (restore overwrites the DB contents afterwards)

Example fix

// before
bd backup restore /path/to/backup
// after
bd init
bd backup restore /path/to/backup

if _, err := os.Stat(filepath.Join(dir, ".beads")); os.IsNotExist(err) {
	return fmt.Errorf("not a beads workspace; run 'bd init' first")
}

s != nil

if err := runBackupRestore(ctx, s, dir, force); err != nil {
	if strings.Contains(err.Error(), "not initialized") {
		// run bd init then retry
	}
	return err
}

When it happens

Trigger: 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.

Common situations: 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.

Related errors

• failed to find backup directory: %w
• backup directory not found: %s Run 'bd backup' first to crea
• no backup destination configured
• failed to remove backup: %w
• failed to create backup dir in git-repo: %w

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