Error: Database out of sync with JSONL. Run 'bd import' first.. bd hangs

[srobertson]

Keep running into this:

Error: Database out of sync with JSONL. Run 'bd import' first.

The JSONL file has been updated (e.g., after 'git pull') but the database
hasn't been imported yet. This would cause you to see stale/incomplete data.

To fix:
bd import # Import JSONL updates to database

Or use daemon mode (auto-imports on every operation):
bd daemon start
bd # Will auto-import before executing

I have the nightmare setup I'm sure

1. Protected main
2. Using worktrees (you know because Anthropic encourages this pattern)

If I run bd import the prompt hangs.. ^C doesn't work.. I have managed on occasion to get this to work if I use nerf all the db files and run db sync...

I've tried bd init --branch beads-metadata and using the --no-daemon flags.. but I'm just floundering...

Got to admit I'm really confused if there's a daemon process why it's not the solution for worktrees behaving nicely... I'd think a centralized actor is what you need...

Anyone managed a setup similar to mine?

[DreadPirateRobertz]

This is a painful combo — protected main + worktrees + JSONL sync. Here's what's happening and how to fix it:

The problem: bd import needs to write to the database, but in protected-branch mode with worktrees, the JSONL source and the database target can get confused about which branch/worktree they're operating on. The hang is likely bd import waiting on a git lock or Dolt lock held by another process.

Immediate fix:

# 1. Kill any hanging bd/dolt processes
pkill -f "bd import"
pkill -f "dolt sql-server"

# 2. Clear any stale locks
find .beads -name "LOCK" -delete
find .beads -name "*.lock" -delete

# 3. Try import again
bd import

Longer-term recommendation: If you're on bd v0.51+, switch to Dolt server mode which eliminates the JSONL sync problem entirely:

bd dolt start
# Now bd reads/writes directly to the Dolt SQL server
# No more JSONL sync needed

For worktree setups: Each worktree should either:

• Share the same Dolt server (set BEADS_DOLT_PORT in your shell env)
• Or use its own embedded Dolt (but then you need bd import/bd export to sync between worktrees)

The "Database out of sync" error is one of the biggest pain points with the JSONL model (see #2489). The Dolt backend was introduced specifically to solve this, but it brought its own set of issues. We're actively working on stabilizing it.