What causes "add backup %s: %w" in gastownhall/beads?

Inspect the wrapped cause (%w) for the real Dolt error and fix the URL or name accordingly

add backup %s: %w

Error message

add backup %s: %w

What it means

BackupAdd runs `CALL DOLT_BACKUP('add', ?, ?)` to register a named backup destination in Dolt and wraps any ExecContext failure as "add backup <name>: <cause>". The library throws it whenever the SQL procedure call itself fails — bad arguments, an invalid URL, or a database-level error. The wrapped error is the authoritative driver/Dolt message.

Source

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

package versioncontrolops

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

View on GitHub (pinned to 71377f2769)

Solutions

Inspect the wrapped cause (%w) for the real Dolt error and fix the URL or name accordingly
Validate the URL scheme with DirToFileURL or url.Parse before calling BackupAdd
Confirm the connection is a Dolt database whose server version supports DOLT_BACKUP
Retry if the cause is a transient connection error

Example fix

// before
_ = versioncontrolops.BackupAdd(ctx, db, "offsite", "htp:/bad-url")
// after
u, err := versioncontrolops.DirToFileURL("/backups/db")
if err != nil { return err }
if err := versioncontrolops.BackupAdd(ctx, db, "offsite", u); err != nil {
	return fmt.Errorf("register backup: %w", err)
}

Defensive patterns

Strategy: validation

Validate before calling

func validateBackupURL(url string) error {
	u, err := url2.Parse(url)
	if err != nil || u.Scheme == "" { return fmt.Errorf("invalid backup url: %q", url) }
	return nil
}
// call validateBackupURL(u) before BackupAdd

Try / catch

if err := vcops.BackupAdd(ctx, db, name, url); err != nil {
	var derr *driverError // unwrap to inspect the %w cause
	if errors.Unwrap(err) != nil && strings.Contains(errors.Unwrap(err).Error(), "unsupported") {
		return fmt.Errorf("DOLT_BACKUP unsupported by server: %w", err)
	}
	return err
}

Prevention

Always build file:// URLs via DirToFileURL, never string concatenation
Validate URL scheme and name non-empty before calling
Confirm server supports DOLT_BACKUP once at startup

When it happens

Trigger: BackupAdd(ctx, db, name, url) when db.ExecContext fails: invalid backup URL, Dolt rejecting the name/URL pair, connection error, or DOLT_BACKUP not supported by the server.

Common situations: Malformed file:// or remote URL passed to DirToFileURL or hand-built; calling against a non-Dolt connection or embedded driver without backup support; duplicate or reserved backup names; network unreachable for remote backups.

Related errors

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