gastownhall/beads · error

register backup remote: %w

Error message

register backup remote: %w

What it means

Returned when registering the file:// backup remote via BackupAdd fails and the error is not an address conflict that can be worked around. This is the hard-failure path of remote registration in BackupDatabase.

Source

Thrown at internal/storage/embeddeddolt/version_control.go:759

	if err != nil {
		return err
	}
	backupName := "backup_export"

	return s.withMutatingDBConn(ctx, func(db versioncontrolops.DBConn) error {
		// Register as a backup remote (idempotent — remove first if exists).
		_ = versioncontrolops.BackupRemove(ctx, db, backupName)
		if err := versioncontrolops.BackupAdd(ctx, 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, db, 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, db, backupName); err != nil {
			return fmt.Errorf("sync to backup: %w", err)
		}
		return nil
	})
}

// RestoreDatabase restores the database from a Dolt backup at dir.
// The dir must exist locally and contain a valid Dolt backup.
// When force is true, an existing database is overwritten.
func (s *EmbeddedDoltStore) 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. Check the wrapped BackupAdd error for the Dolt root cause
2. Ensure the backup directory path is absolute, exists, and is a plain directory
3. If a remote with the same name exists at another URL, remove it (dolt backup remove / bd equivalent) and retry
4. Verify Dolt version compatibility for backup remote operations

// ensure a clean absolute directory path before registering
abs, err := filepath.Abs(dir)
if err != nil { return err }
if info, err := os.Stat(abs); err != nil || !info.IsDir() {
    return fmt.Errorf("%%s must be an existing directory", abs)
}

if err := store.BackupDatabase(ctx, dir); err != nil {
    if strings.Contains(err.Error(), "register backup remote") { /* inspect existing remotes, remove stale ones, retry */ }
}

When it happens

Trigger: BackupDatabase calls BackupAdd(ctx, db, backupName, backupURL) with a malformed URL (DirToFileURL edge case), an invalid remote name, or a Dolt-level registration error not matching ExtractAddressConflictName.

Common situations: Backup dir path with characters that break file:// URL formation; Dolt refusing to add a remote with a duplicate name pointing at a DIFFERENT URL; database in a state preventing remote registration.

Related errors

• no backup destination configured
• failed to remove backup: %w
• failed to get current commit: %w
• storage backend does not support backup operations
• failed to get current commit for state: %w

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