What causes "no database — run 'bd init' or 'bd bootstrap' first" in gastownhall/beads?

Run `bd init` in the project root to create the database, then re-run the import

no database — run 'bd init' or 'bd bootstrap' first

Error message

no database — run 'bd init' or 'bd bootstrap' first

What it means

bd import was invoked without an open database handle. In the classic (embedded) import path, the shared `store` is nil because no repository has been initialized, so the command aborts instead of writing into nothing. bd requires an explicit `bd init` (create empty DB) or `bd bootstrap` (init plus seed context) before any record operations.

Source

Thrown at cmd/bd/import.go:229

	UpdatedIssues       []ImportChange `json:"updated_issues,omitempty"`
	TieKeptLocalIDs     []string       `json:"tie_kept_local_ids,omitempty"`
	StaleSkippedIDs     []string       `json:"stale_skipped_ids,omitempty"`
	SkippedDependencies []string       `json:"skipped_dependencies,omitempty"`
	DryRun              bool           `json:"dry_run,omitempty"`
}

func runImportFromReader(ctx context.Context, r io.Reader, source string) error {
	issues, memories, err := parseImportRecords(r)
	if err != nil {
		return err
	}

	if usesProxiedServer() {
		return runImportRecordsProxied(ctx, issues, memories, source)
	}

	if store == nil {
		return fmt.Errorf("no database — run 'bd init' or 'bd bootstrap' first")
	}
	return runImportRecordsClassic(ctx, issues, memories, source)
}

// parseImportRecords scans one JSONL stream into issue rows and memory
// records — the `bd import` / `bd import -` parse loop, shared by the classic
// and proxied modes. Same record vocabulary as parseJSONLFile (the bootstrap
// reader): the optional _schema header and tombstones are skipped, and the
// "wisp_plane" boolean is honored as the explicit wisps-plane marker (and
// the legacy "wisp" alias for "ephemeral") via applyImportWispPlane.
func parseImportRecords(r io.Reader) ([]*types.Issue, []memoryRecord, error) {
	scanner := bufio.NewScanner(r)
	scanner.Buffer(make([]byte, 0, 1024*1024), 64*1024*1024)

	var issues []*types.Issue
	var memories []memoryRecord

	for scanner.Scan() {

View on GitHub (pinned to 71377f2769)

Solutions

Run `bd init` in the project root to create the database, then re-run the import
Run `bd bootstrap` if you want init plus seeded project context
Verify you are in the intended directory (`pwd`) and that `.beads/` exists
In scripts/CI, add an init guard: `[ -d .beads ] || bd init` before importing

Example fix

// before (fresh checkout, CI script)
bd import issues.jsonl   # error: no database
// after
bd init
bd import issues.jsonl

Defensive patterns

Strategy: validation

Validate before calling

if [ ! -d .beads ]; then bd init; fi
bd import data.jsonl

Try / catch

if ! bd import data.jsonl; then
  bd init
  bd import data.jsonl
fi

Prevention

Always run bd init (or bd bootstrap) before scripted imports
Check for .beads/ directory existence in CI before any bd command
Pin the working directory in scripts so import never runs in the wrong repo
Add a bd doctor step to pipeline preflight checks

When it happens

Trigger: Running `bd import file.jsonl` (or `bd import -`) in a directory with no `.beads` database, or after `bd db --delete`/a failed init, so runImportFromReader reaches runImportRecordsClassic with store==nil.

Common situations: Cloning a repo whose .beads data was gitignored; running bd in the wrong working directory; a fresh CI container that skips the init step; corrupted or deleted beads database file.

Related errors

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