gastownhall/beads · error

target repo %s is not initialized; refusing to initialize it

Error message

target repo %s is not initialized; refusing to initialize it during dry-run

What it means

For local filesystem targets, openDryRunTargetStore checks that <repo>/.beads/metadata.json exists before opening anything. If it is missing, the function refuses to proceed: dry-run must never initialize (create) a target repository as a side effect. The expanded absolute target path is included in the message.

Source

Thrown at cmd/bd/create.go:988

		cache, err := remotecache.DefaultCache()
		if err != nil {
			return nil, fmt.Errorf("failed to initialize remote cache: %w", err)
		}
		// The dry-run parent lookup only reads from this cached remote store.
		// Do not add writes here; dry-runs must not mutate cached remotes.
		store, err := cache.OpenStore(ctx, repoPath, newPreviewStoreFromConfig)
		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 {

View on GitHub (pinned to 71377f2769)

Solutions

1. Run `bd init` in the target repo to create .beads/metadata.json, then retry the dry-run.
2. Double-check the --repo path — os.Stat failed on the exact expanded path shown in the message; verify the intended checkout is used.
3. If .beads was deleted accidentally, restore it from git (the metadata.json is normally committed) or re-init and re-sync.
4. Point the dry-run at an already-initialized repo clone instead of an uninitialized one.

Example fix

// before: dry-run against an uninitialized repo
bd create --dry-run "Task" --repo ../new-service
// error: target repo ../new-service is not initialized...
// after: initialize the target repo first
cd ../new-service && bd init
bd create --dry-run "Task" --repo ../new-service

// Check the target is an initialized beads repo before any dry-run.
targetPath := routing.ExpandPath(repoPath)
if _, err := os.Stat(filepath.Join(targetPath, ".beads", "metadata.json")); os.IsNotExist(err) {
    return fmt.Errorf("%s is not an initialized beads repo; run `bd init` there first", targetPath)
}

store, err := openDryRunTargetStore(ctx, repoPath)
if err != nil {
    if strings.Contains(err.Error(), "not initialized; refusing to initialize it during dry-run") {
        fmt.Fprintf(os.Stderr, "Target repo is not initialized. Run `cd %s && bd init` first.\n", repoPath)
        os.Exit(1)
    }
    return err
}

When it happens

Trigger: bd create --dry-run --repo /path/to/repo where /path/to/repo/.beads/metadata.json does not exist: the directory was never `bd init`ed, the .beads dir was deleted, or --repo points at the wrong (empty/new) directory.

Common situations: Running dry-run against a freshly cloned repo that lacks .beads (repo not initialized with bd); pointing --repo at the wrong checkout; a wiped or renamed .beads directory; testing in a scratch directory that was never initialized.

Related errors

• failed to inspect target repo %s: %w
• reading reason file %q: %w
• failed to initialize remote cache: %w
• dry-run parent lookup requires an existing cached remote sto
• failed to open target store for dry-run: %w

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