Fix: beads v0.49.4 migration failure (no such column: spec_id)

beads-spec_id-fix-guide.md

Fix: beads v0.49.4 migration failure (no such column: spec_id)

---

created: 2026-02-06 updated: 2026-02-06 references:

• steveyegge/beads#1516
• steveyegge/beads#1535
• steveyegge/beads#1538

---

Fix: beads v0.49.4 migration failure (no such column: spec_id)

After upgrading beads to v0.49.4 via Homebrew, all bd commands fail with:

sqlite3: SQL logic error: no such column: spec_id

bd migrate also fails because it can't open the database.

What is spec_id?

spec_id is a new optional field added in v0.49.4 (#1372) for linking issues to specification documents. It defaults to empty string and is only populated if you explicitly set it via bd update <id> --spec-id <ref>. The fix below adds this column with the correct default — existing issues are unaffected.

Fix: Manual column fix + doctor

Add the missing column manually, then let bd doctor --fix handle the rest:

# 1. Add the missing column
sqlite3 your-project/.beads/beads.db \
  "ALTER TABLE issues ADD COLUMN spec_id TEXT DEFAULT '';"

# 2. Verify beads works
bd list

# 3. Run doctor to complete migration
# This fixes ALL fixable warnings: schema version bump, gitignore updates,
# sync divergence, uncommitted changes, and any other issues doctor detects.
yes | bd doctor --fix

Verify

bd doctor 2>&1 | grep "Database version"
# Expected: ✓  Database version 0.49.4

Affected versions

• From: any version before 0.49.4 (confirmed with 0.49.1, 0.49.3)
• To: 0.49.4

I used this on many repos and now it works great. the "clean slate" is a bit complicated so I removed that option.

---

NOT by Claude or any agent.