gastownhall/beads · error

backup source is not a directory: %s

Error message

backup source is not a directory: %s

What it means

Returned by RestoreDatabase when the source path exists but is not a directory. A Dolt backup source must be a directory containing backup data, so a file at that path is rejected with this plain message.

Source

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

			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. Extract any archive into a directory first, then restore from that directory
2. Point restore at the backup directory, not a file inside or a sibling file
3. Verify with `ls -la <path>` that it is a directory containing Dolt backup data
4. If a file occupies the expected path, choose a different directory path

Example fix

// before
store.RestoreDatabase(ctx, "/backups/beads.tar.gz", false)
// after
exec.Command("tar", "-xzf", "/backups/beads.tar.gz", "-C", "/tmp/restore")
store.RestoreDatabase(ctx, "/tmp/restore/beads", false)

info, err := os.Stat(dir)
if err != nil || !info.IsDir() {
    return fmt.Errorf("restore source must be an extracted backup directory: %%s", dir)
}

When it happens

Trigger: Calling RestoreDatabase(ctx, dir, force) where os.Stat succeeds but IsDir() is false — pointing restore at a zip/tar archive, a database file, or a symlink to a file instead of the extracted backup directory.

Common situations: Trying to restore directly from a compressed archive without extracting it; passing the beads .bdb file instead of the backup dir; restoring a path exported as a single file by another tool.

Related errors

• backup source does not exist: %w
• 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/eed561a2d7d68671. Report an issue: GitHub.