gastownhall/beads · error

failed to commit restore: %w

Error message

failed to commit restore: %w

What it means

After restoring the database files, runBackupRestore calls s.Commit(ctx, "bd backup restore") to record a Dolt commit marking the restore. Any commit error other than the benign 'nothing to commit' case is wrapped in this error, signaling the restored data was written but the post-restore commit could not be created.

Source

Thrown at cmd/bd/backup_restore.go:112

	}

	// After a force restore, the database's _project_id may differ from
	// metadata.json (the backup came from a different project). Sync
	// metadata.json to match the restored database so the identity check
	// doesn't reject subsequent connections.
	if force {
		if err := syncProjectIDFromDB(ctx, s); err != nil {
			fmt.Fprintf(os.Stderr, "Warning: failed to sync project ID after restore: %v\n", err)
		}
	}

	// Register the restore source as the backup destination so
	// `bd backup sync` works immediately without a separate `bd backup add`.
	registerBackupRemote(ctx, bs, dir)

	if err := s.Commit(ctx, "bd backup restore"); err != nil {
		if !strings.Contains(err.Error(), "nothing to commit") {
			return fmt.Errorf("failed to commit restore: %w", err)
		}
	}

	return nil
}

// registerBackupRemote registers dir as the default backup remote and saves
// the local backup config. Errors are non-fatal warnings.
func registerBackupRemote(ctx context.Context, bs storage.BackupStore, dir string) {
	backupURL := resolveDoltBackupURL(dir)

	// Remove + re-add to handle the case where a remote already exists.
	_ = bs.BackupRemove(ctx, defaultDoltBackupName)
	if err := bs.BackupAdd(ctx, defaultDoltBackupName, backupURL); err != nil {
		fmt.Fprintf(os.Stderr, "Warning: failed to register backup remote: %v\n", err)
		return
	}
	if err := saveDoltBackupConfig(backupURL); err != nil {

View on GitHub (pinned to 71377f2769)

Solutions

1. Inspect the wrapped error for the root Dolt/driver cause
2. Check for and remove stale Dolt lock files in the .beads database directory
3. Verify free disk space and filesystem writability
4. Re-run the restore ('bd backup restore <dir>') so the commit step executes on a clean state

Example fix

// before
if err := s.Commit(ctx, "bd backup restore"); err != nil {
	return fmt.Errorf("failed to commit restore: %w", err)
}
// after
if err := s.Commit(ctx, "bd backup restore"); err != nil {
	if !strings.Contains(err.Error(), "nothing to commit") {
		return fmt.Errorf("failed to commit restore: %w", err)
	}
}

// pre-check writability and space before restore
if err := unix.Access(beadsDir, unix.W_OK); err != nil { return err }
if stat, err := os.Stat(beadsDir); err == nil && stat.Size() == 0 { /* suspicious target */ }

if err := s.Commit(ctx, "bd backup restore"); err != nil {
	if !strings.Contains(err.Error(), "nothing to commit") {
		if isTransient(err) { time.Sleep(backoff); retryCommit() }
		return fmt.Errorf("failed to commit restore: %w", err)
	}
}

When it happens

Trigger: bs.RestoreDatabase succeeds but s.Commit fails — e.g. Dolt lock contention, disk full, corrupted merge/commit state after restore, or a driver error writing the new HEAD.

Common situations: Disk-full during restore; leftover dolt lock files from a crashed process; restored snapshot whose commit graph confuses the working set; read-only filesystem after restore.

Related errors

• failed to commit orphaned dependency removals: %w
• failed to commit federation peer: %w
• failed to stage %s before commit: %w
• publish working set after SQL commit: %w: %w
• stage and commit after regular SQL commit: %w: %w

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