gastownhall/beads · error

storage backend does not support backup operations

Error message

storage backend does not support backup operations

What it means

After obtaining the storage handle, runBackupRestore unwraps it with storage.UnwrapStore and asserts it implements storage.BackupStore. Backends that do not implement RestoreDatabase/backup operations fail this type assertion and produce this error. Restore is only supported by Dolt-native storage.

Source

Thrown at cmd/bd/backup_restore.go:89

		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)
		}
	}

	// Register the restore source as the backup destination so
	// `bd backup sync` works immediately without a separate `bd backup add`.

View on GitHub (pinned to 71377f2769)

Solutions

1. Use the default Dolt storage backend for backup/restore operations
2. If running against the server/proxied mode, perform restore with a direct (local) database handle
3. Upgrade beads so the storage driver in use implements the BackupStore interface
4. Check which backend is active (env/config) and switch back to Dolt

Example fix

// before
bs, ok := storage.UnwrapStore(s).(storage.BackupStore)
if !ok { ... } // fails on non-Dolt backend
// after
// run against a local Dolt-backed store, e.g. unset server mode:
// BD_SERVER= bd backup restore /path/to/backup

if _, ok := storage.UnwrapStore(s).(storage.BackupStore); !ok {
	return fmt.Errorf("current backend (%T) does not support backup restore; use Dolt storage", s)
}

bs, ok := storage.UnwrapStore(s).(storage.BackupStore)
if !ok { /* fall back or error */ }

bs, ok := storage.UnwrapStore(s).(storage.BackupStore)
if !ok {
	return fmt.Errorf("backend %T lacks BackupStore; rerun without server/proxy mode", s)
}

When it happens

Trigger: 'bd backup restore' is invoked with a storage backend whose concrete type does not implement storage.BackupStore — e.g. a non-Dolt driver, a remote/proxied handle that doesn't expose backup ops, or a mock in tests.

Common situations: Using an alternative storage driver or server mode where the handle is proxied and lacks BackupStore; version mismatch where an older backend predates the BackupStore interface; unit tests injecting a plain DoltStorage without backup support.

Related errors

• storage backend does not support backup operations
• failed to get current commit for state: %w
• no store is open for this workspace
• not found
• db: ChildCounterSQLRepository.NextChildID: parentID must not

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