gastownhall/beads · error

register backup remote: %w

Error message

register backup remote: %w

What it means

BackupDatabase called versioncontrolops.BackupAdd to register the destination directory as a file:// Dolt backup remote, and the registration failed with an error that was not an address conflict (no recoverable existing remote name was extractable). The backup aborts before any data is synced.

Source

Thrown at internal/storage/dolt/store.go:1324

	syncDB, err := s.oneShotConn(0)
	if err != nil {
		return err
	}
	defer syncDB.Close()

	// Register as a backup remote (idempotent — remove first if exists).
	_ = versioncontrolops.BackupRemove(ctx, s.db, backupName)
	if err := versioncontrolops.BackupAdd(ctx, s.db, backupName, backupURL); err != nil {
		// Another backup (e.g. "default" registered by `bd backup init`) may
		// already point to this URL. In that case, sync using the existing
		// remote name rather than failing.
		if conflict := versioncontrolops.ExtractAddressConflictName(err); conflict != "" {
			if syncErr := versioncontrolops.BackupSync(ctx, syncDB, conflict); syncErr != nil {
				return fmt.Errorf("sync to backup: %w", syncErr)
			}
			return nil
		}
		return fmt.Errorf("register backup remote: %w", err)
	}
	if err := versioncontrolops.BackupSync(ctx, syncDB, backupName); err != nil {
		return fmt.Errorf("sync to backup: %w", err)
	}
	return nil
}

// RestoreDatabase restores the database from a Dolt backup at dir.
// When force is true, an existing database is overwritten.
func (s *DoltStore) RestoreDatabase(ctx context.Context, dir string, force bool) error {
	info, err := os.Stat(dir)
	if err != nil {
		return fmt.Errorf("backup source does not exist: %w", err)
	}
	if !info.IsDir() {
		return fmt.Errorf("backup source is not a directory: %s", dir)
	}

View on GitHub (pinned to 71377f2769)

Solutions

1. Read the wrapped BackupAdd error — it names the concrete Dolt/SQL failure; fix that cause first.
2. If the real problem is an existing remote at the same URL that failed conflict extraction, list existing backups (`dolt backup -v`) and remove the stale one, then retry.
3. Confirm your Dolt server/version supports backup remotes (CALL DOLT_BACKUP); upgrade Dolt if the call is unknown.
4. Check connectivity to s.db — registration goes over the SQL connection, so connection errors surface here.

Example fix

// before: stale remote blocks registration
// after: remove the stale remote then retry
_, _ = db.ExecContext(ctx, "CALL DOLT_BACKUP('remove', 'default')")
err := store.BackupDatabase(ctx, dir)

// probe that backup registration is supported before calling
if err := db.PingContext(ctx); err != nil {
    return fmt.Errorf("cannot reach dolt to register backup: %w", err)
}
// list existing backups first to avoid conflicts
rows, _ := db.Query("CALL DOLT_BACKUP('-v')")

if err := store.BackupDatabase(ctx, dir); err != nil {
    if strings.Contains(err.Error(), "register backup remote") {
        // remove stale remotes then retry once
        _, _ = db.ExecContext(ctx, "CALL DOLT_BACKUP('remove', 'beads-backup')")
        err = store.BackupDatabase(ctx, dir)
    }
}

When it happens

Trigger: BackupAdd(ctx, s.db, backupName, backupURL) returned a non-conflict error — the Dolt SQL layer rejected the backup registration, e.g. the remote name is invalid, the SQL connection to s.db failed, or the server does not support the backup operation in this mode.

Common situations: Embedded vs server mode mismatch where backup operations are unavailable; invalid backup name characters; Dolt version too old for the backup remote API; connection failure to the store's database at registration time.

Related errors

• sync to backup: %w
• register backup remote: %w
• no backup destination configured
• failed to remove backup: %w
• failed to get current commit: %w

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