gastownhall/beads · error

sync backup

Error message

sync backup %s: %w

What it means

BackupSync runs `CALL DOLT_BACKUP('sync', ?)` to push the database to a previously registered backup destination, wrapping failures as "sync backup <name>: <cause>". It throws when the push to the backup remote fails or the named backup does not exist. The wrapped driver error carries the underlying reason.

Solutions

1. Verify the name was registered first via BackupAdd (or `dolt backup add`)
2. Check the wrapped cause for unreachable/read-only destination and fix storage or network
3. List configured backups (SELECT from dolt_backup or `dolt backup -v`) to confirm the name
4. Retry transient network failures with backoff

Example fix

// before
if err := vcops.BackupSync(ctx, db, "offsite"); err != nil { panic(err) }
// after
if err := vcops.BackupAdd(ctx, db, "offsite", backupURL); err != nil { return err }
if err := vcops.BackupSync(ctx, db, "offsite"); err != nil {
	return fmt.Errorf("push to offsite backup: %w", err)
}

// ensure backup exists first
if err := vcops.BackupAdd(ctx, db, name, url); err != nil { return err }
// then safe to sync

if err := vcops.BackupSync(ctx, db, name); err != nil {
	if isTransient(errors.Unwrap(err)) {
		return retryWithBackoff(3, func() error { return vcops.BackupSync(ctx, db, name) })
	}
	return err
}

When it happens

Trigger: BackupSync(ctx, db, name) when db.ExecContext fails: backup name not registered (no prior BackupAdd), destination unreachable or read-only, or the sync write errors mid-transfer.

Common situations: Syncing a backup registered in a different Dolt directory/DB; destination filesystem full or permissions denied; network outage to a remote backup; typo in the backup name.

Related errors

• failed to remove backup
• fetch failed
• fetch failed
• pull from
• pull

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

Appendix: source

Thrown at internal/storage/versioncontrolops/backup.go:21

import (
	"context"
	"fmt"
	"path/filepath"
	"strings"
)

// BackupAdd registers a Dolt backup destination.
func BackupAdd(ctx context.Context, db DBConn, name, url string) error {
	if _, err := db.ExecContext(ctx, "CALL DOLT_BACKUP('add', ?, ?)", name, url); err != nil {
		return fmt.Errorf("add backup %s: %w", name, err)
	}
	return nil
}

// BackupSync pushes the database to the named backup destination.
func BackupSync(ctx context.Context, db DBConn, name string) error {
	if _, err := db.ExecContext(ctx, "CALL DOLT_BACKUP('sync', ?)", name); err != nil {
		return fmt.Errorf("sync backup %s: %w", name, err)
	}
	return nil
}

// BackupRemove removes a configured Dolt backup destination.
func BackupRemove(ctx context.Context, db DBConn, name string) error {
	if _, err := db.ExecContext(ctx, "CALL DOLT_BACKUP('rm', ?)", name); err != nil {
		return fmt.Errorf("remove backup %s: %w", name, err)
	}
	return nil
}

// BackupRestore restores a database from a backup at the given URL into
// the named database. When force is true, an existing database with the
// same name is overwritten. Mirrors the CLI: dolt backup restore [--force] <url> <db_name>
func BackupRestore(ctx context.Context, db DBConn, url, dbName string, force bool) error {
	if force {
		if _, err := db.ExecContext(ctx, "CALL DOLT_BACKUP('restore', '--force', ?, ?)", url, dbName); err != nil {

View on GitHub (pinned to 71377f2769)