gastownhall/beads · error

backup source does not exist: %w

Error message

backup source does not exist: %w

What it means

Returned by RestoreDatabase when the source backup directory cannot be stat-ed, i.e. it does not exist or is inaccessible. Restore requires a valid local Dolt backup directory, so it fails fast with the os.Stat error wrapped.

Source

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

				}
				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)
	}

	backupURL, err := versioncontrolops.DirToFileURL(dir)
	if err != nil {
		return err
	}

	return s.withMutatingDBConn(ctx, func(db versioncontrolops.DBConn) error {
		return versioncontrolops.BackupRestore(ctx, db, backupURL, s.database, force)
	})
}

View on GitHub (pinned to 71377f2769)

Solutions

1. Verify the backup directory path exists: ls <dir>
2. Mount the volume/drive containing the backup before restoring
3. Fix path typos and use absolute paths
4. Recreate the backup from a healthy replica if the source is gone

Example fix

// before
store.RestoreDatabase(ctx, "/mnt/backup/beads", true)
// after
if _, err := os.Stat("/mnt/backup/beads"); err != nil {
    return fmt.Errorf("mount/locate backup first: %%w", err)
}
store.RestoreDatabase(ctx, "/mnt/backup/beads", true)

info, err := os.Stat(dir)
if err != nil {
    return fmt.Errorf("backup source %%s unavailable: %%w", dir, err)
}
if !info.IsDir() { return fmt.Errorf("%%s is not a directory", dir) }

if err := store.RestoreDatabase(ctx, dir, false); err != nil {
    var pe *fs.PathError
    if errors.As(err, &pe) && os.IsNotExist(pe) { /* mount/locate backup before retry */ }
}

When it happens

Trigger: Calling RestoreDatabase(ctx, dir, force) with a dir that was deleted, moved, never created, is on an unmounted volume, or has permission problems.

Common situations: Restoring on a new machine where the backup volume isn't mounted; typo'd restore path; backup directory cleaned up by a retention job before the restore attempt.

Related errors

• backup source is not a directory: %s
• dolt path is not executable
• failed to commit restore: %w
• failed to remove Dolt database: %w
• measure active database directory %q: %w

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