gastownhall/beads · error

sync backup %s: %w

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.

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)

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: %w
• pull: %w
• push: %w
• fetch failed: %w
• sync to backup: %w

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