What causes "failed to find backup directory: %w" in gastownhall/beads?

Pass the backup directory explicitly: 'bd backup restore /path/to/backup'

failed to find backup directory: %w

Error message

failed to find backup directory: %w

What it means

In 'bd backup restore', when no directory argument is supplied, the tool resolves the default backup location via backupDir(). If that resolution fails (typically because no backup has been registered/added in this project's config), this wrapped error is returned and restore aborts before validating the directory.

Source

Thrown at cmd/bd/backup_restore.go:54

			return HandleErrorRespectJSON("backup restore is not supported in proxied-server mode")
		}
		evt := metrics.NewCommandEvent("backup-restore")
		defer func() {
			if c := metrics.Global(); c != nil {
				c.CloseEventAndAdd(evt)
			}
		}()

		ctx := rootCtx

		var dir string
		if len(args) > 0 {
			dir = args[0]
		} else {
			var err error
			dir, err = backupDir()
			if err != nil {
				return fmt.Errorf("failed to find backup directory: %w", err)
			}
		}

		if err := validateBackupRestoreDir(dir); err != nil {
			return err
		}

		force, _ := cmd.Flags().GetBool("force")

		if err := runBackupRestore(ctx, store, dir, force); err != nil {
			return err
		}

		if !jsonOutput {
			fmt.Printf("%s Restore complete\n", ui.RenderPass("✓"))
		}

		return nil

View on GitHub (pinned to 71377f2769)

Solutions

Pass the backup directory explicitly: 'bd backup restore /path/to/backup'
Register a default backup location first with 'bd backup add <dest>'
Check .beads config for the backup destination entry and fix/remove a stale one
Create a backup first with 'bd backup' so a default directory exists

Example fix

// before
bd backup restore
// after
bd backup restore ~/.beads-backups/myproject  # or: bd backup add <dest> first

Defensive patterns

Strategy: validation

Validate before calling

if dir == "" {
	if _, err := os.Stat(defaultBackupDir()); err != nil {
		return fmt.Errorf("no backup configured; run 'bd backup add <dest>' first")
	}
}

Type guard

dir != "" && os.Stat(dir) == nil

Try / catch

dir, err := backupDir()
if err != nil {
	return fmt.Errorf("failed to find backup directory: %w\nTip: run 'bd backup add <dest>' or pass a directory argument", err)
}

Prevention

Always register a default with 'bd backup add <dest>' after bd init
Pass the backup directory explicitly in scripts instead of relying on defaults
Keep .beads config under version control or backed up so backup destinations survive machine changes
Verify with 'bd backup list'/config that a destination exists before scripting restores

When it happens

Trigger: Running 'bd backup restore' with no positional dir argument while backupDir() cannot determine the backup directory — e.g. no backup destination has ever been added via 'bd backup add' or the beads config is missing/unreadable.

Common situations: New machine or fresh clone where backup config was never set up; typos or missing config.yaml in .beads; running restore before ever running 'bd backup'; BEADS_DIR pointing at a directory without backup configuration.

Related errors

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