gastownhall/beads · error

backup directory not found: %s Run 'bd backup' first to crea

Error message

backup directory not found: %s
Run 'bd backup' first to create a backup

What it means

validateBackupRestoreDir checks that the given restore source directory exists via os.Stat before performing the restore. If the path does not exist, this friendly error is returned, reminding the user that a backup must be created first. It prevents restoring from a typo'd or never-created path.

Source

Thrown at cmd/bd/backup_restore.go:163

		return fmt.Errorf("%s; %s", activeWorkspaceNotFoundError(), diagHint())
	}

	cfg, err := configfile.Load(beadsDir)
	if err != nil {
		return err
	}

	if cfg.ProjectID == dbID {
		return nil // already in sync
	}

	cfg.ProjectID = dbID
	return cfg.Save(beadsDir)
}

func validateBackupRestoreDir(dir string) error {
	if _, err := os.Stat(dir); os.IsNotExist(err) {
		return fmt.Errorf("backup directory not found: %s\nRun 'bd backup' first to create a backup", dir)
	}
	return nil
}

View on GitHub (pinned to 71377f2769)

Solutions

1. Verify the path exists (ls the directory) and correct any typo
2. Create a backup first with 'bd backup' (or 'bd backup sync')
3. If the backup lives elsewhere, pass its absolute path to restore
4. Check for cwd/relative-path surprises — prefer absolute paths in scripts

Example fix

// before
bd backup restore ./bacup
// after
bd backup   # create a backup
bd backup restore ~/.beads/backups/myproject

if info, err := os.Stat(dir); os.IsNotExist(err) || !info.IsDir() {
	return fmt.Errorf("backup directory %q does not exist; run 'bd backup' first", dir)
}

func dirExists(p string) bool { info, err := os.Stat(p); return err == nil && info.IsDir() }

if err := validateBackupRestoreDir(dir); err != nil {
	// prompt user or auto-create backup:
	// exec.Command("bd", "backup").Run()
	return err
}

When it happens

Trigger: 'bd backup restore <dir>' (or the resolved default dir) points to a path that does not exist on disk — os.Stat returns an IsNotExist error.

Common situations: Typo in the backup path; backup was deleted or moved; running restore on a new machine where the backup directory was never created; relative path resolved from the wrong cwd.

Related errors

• failed to find backup directory: %w
• database is not initialized. Run 'bd init' first
• dolt binary not found
• no backup destination configured
• failed to remove backup: %w

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