gastownhall/beads · error

failed to open target store for dry-run: %w

Error message

failed to open target store for dry-run: %w

What it means

After confirming the target repo is initialized, openDryRunTargetStore opens a read-only preview store via newPreviewStoreFromConfig(ctx, beadsDir). This error wraps any failure from that step — typically the Dolt database under .beads cannot be opened: corrupt database files, schema/version mismatch, missing or invalid metadata, or driver-level open failure. The repo passed the existence check but its store is not usable.

Source

Thrown at cmd/bd/create.go:995

		if err != nil {
			return nil, fmt.Errorf("dry-run parent lookup requires an existing cached remote store for %s: %w", repoPath, err)
		}
		return store, nil
	}

	targetPath := routing.ExpandPath(repoPath)
	beadsDir := filepath.Join(targetPath, ".beads")
	metadataPath := filepath.Join(beadsDir, "metadata.json")
	if _, err := os.Stat(metadataPath); err != nil {
		if os.IsNotExist(err) {
			return nil, fmt.Errorf("target repo %s is not initialized; refusing to initialize it during dry-run", targetPath)
		}
		return nil, fmt.Errorf("failed to inspect target repo %s: %w", targetPath, err)
	}

	store, err := newPreviewStoreFromConfig(ctx, beadsDir)
	if err != nil {
		return nil, fmt.Errorf("failed to open target store for dry-run: %w", err)
	}
	return store, nil
}

// isAmbiguousRepoTarget reports whether an explicit --repo value is a
// bare/relative filesystem path (not absolute, not "~/"-prefixed). Such a
// value silently resolves against the current working directory (see
// routing.ExpandPath) rather than failing, so a misresolved value (e.g. a
// typo) previously wrote a bead into a brand-new, disconnected database
// instead of erroring (bd-8d3f).
func isAmbiguousRepoTarget(repoFlagChanged bool, repoOverride string) bool {
	return repoFlagChanged && !filepath.IsAbs(repoOverride) && !strings.HasPrefix(repoOverride, "~/")
}

// ensureBeadsDirForPath ensures a beads directory exists at the target path.
// If the .beads directory doesn't exist, it creates it and initializes with
// the same prefix as the source store (T010, T012: prefix inheritance).
//

View on GitHub (pinned to 71377f2769)

Solutions

1. Read the wrapped cause (%w) from newPreviewStoreFromConfig to see the exact open failure and address it.
2. Check beads version mismatch — run `bd --version`, upgrade the binary (or `bd upgrade`) so it can read the database, and run any advertised migration/doctor command.
3. Run `bd doctor` to detect and repair common database/metadata problems.
4. Restore .beads from git or re-sync with the remote (bd dolt pull) if the local database is corrupt.
5. As a last resort, re-init the repo (bd init) and re-import/sync, keeping the issues.jsonl export as the recovery source.

Example fix

// before: DB created by newer beads version
bd create --dry-run "Task" --repo .   // failed to open target store for dry-run: schema ...
// after: upgrade binary and run doctor
bd upgrade
bd doctor
bd create --dry-run "Task" --repo .

// Detect version skew and metadata validity before opening the store.
out, err := exec.Command("bd", "--version").Output()
if err == nil && olderThanSupported(string(out)) {
    return fmt.Errorf("bd binary is older than the repo's database; run `bd upgrade` first")
}
if _, err := os.Stat(filepath.Join(repoPath, ".beads", "metadata.json")); err != nil {
    return fmt.Errorf("target metadata missing or unreadable: %w", err)
}

store, err := openDryRunTargetStore(ctx, repoPath)
if err != nil {
    if strings.Contains(err.Error(), "failed to open target store for dry-run") {
        fmt.Fprintf(os.Stderr, "Cannot open target store: %v\nRun `bd doctor` and `bd upgrade`; restore .beads from git if corrupt.\n", err)
        os.Exit(1)
    }
    return err
}

When it happens

Trigger: bd create --dry-run --repo <local-path> where .beads/metadata.json exists but newPreviewStoreFromConfig fails: corrupted Dolt database in .beads, beads version wrote a newer schema/DB format than the installed binary supports, lock files left by a crashed process, or invalid metadata.json content.

Common situations: Mixed beads versions across machines (newer binary created the DB, older binary opens it); interrupted bd process leaving the Dolt database in a bad state; disk corruption or partially-synced .beads; manually edited metadata.json.

Related errors

• failed to initialize remote cache: %w
• dry-run parent lookup requires an existing cached remote sto
• ErrTransaction
• ErrQuery
• ErrScan

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