gastownhall/beads · error

legacy SQLite release marker: %w

Error message

legacy SQLite release marker: %w

What it means

Before reading any data, verify() queries the metadata table for the key 'bd_version', which identifies which release produced the legacy database. If that query fails — typically because the metadata table or the bd_version row is missing (sql.ErrNoRows), or the table doesn't exist — the error is wrapped as 'legacy SQLite release marker: ...'. The library only migrates exact, audited layouts, so an unreadable version marker means the file is not a recognized legacy database.

Source

Thrown at internal/migration/legacysqlite/reader.go:309

	if err := loadChildren(ctx, tx, issues); err != nil {
		return err
	}
	if err := tx.Commit(); err != nil {
		return err
	}
	enc := json.NewEncoder(out)
	for _, issue := range issues {
		if err := enc.Encode(issue); err != nil {
			return err
		}
	}
	return nil
}

func verify(ctx context.Context, db *sql.Tx) error {
	var version string
	if err := db.QueryRowContext(ctx, "SELECT value FROM metadata WHERE key = 'bd_version'").Scan(&version); err != nil {
		return fmt.Errorf("legacy SQLite release marker: %w", err)
	}
	if !acceptedVersions[version] {
		return fmt.Errorf("unsupported legacy SQLite release %q", version)
	}
	for table, want := range schema {
		if err := verifyTable(ctx, db, table, want); err != nil {
			return err
		}
	}
	for _, table := range []string{"metadata", "issues", "dependencies", "labels", "comments"} {
		if err := verifyFKs(ctx, db, table); err != nil {
			return err
		}
	}
	return nil
}

func verifyTable(ctx context.Context, db *sql.Tx, table, want string) error {

View on GitHub (pinned to 71377f2769)

Solutions

1. Confirm you are pointing at the correct legacy beads SQLite file (it should contain a metadata table with a bd_version row: sqlite3 f.db "SELECT * FROM metadata")
2. If the database predates the marker, open it with the matching old bd release first and let it upgrade/re-export
3. If the metadata table is missing/corrupt, restore the database from backup
4. Run PRAGMA integrity_check to rule out corruption before retrying

Example fix

// inspect the source before exporting
$ sqlite3 beads.db "SELECT key, value FROM metadata;"
-- if this errors with 'no such table: metadata', this is not a beads legacy DB
$ bd migrate --legacy ./correct/beads.db --output issues.jsonl

// pre-flight: confirm the file is a recognized legacy beads database
func hasVersionMarker(dbPath string) (string, error) {
	db, err := sql.Open("sqlite3", dbPath+"?mode=ro"); if err != nil { return "", err }
	defer db.Close()
	var v string
	err = db.QueryRow("SELECT value FROM metadata WHERE key = 'bd_version'").Scan(&v)
	return v, err
}

if err := legacysqlite.Export(ctx, src, out, os.Stdout); err != nil {
	var se *string // inspect wrapped cause
	if strings.Contains(err.Error(), "legacy SQLite release marker") {
		return fmt.Errorf("%s is not a recognized legacy beads DB (missing bd_version); check the path", src)
	}
	return err
}

When it happens

Trigger: Export -> read -> verify: SELECT value FROM metadata WHERE key='bd_version' returns an error — most commonly 'no such table: metadata' on a non-bd SQLite file, or sql.ErrNoRows ('sql: no rows in result set') when the row is absent, or 'database disk image is malformed' on corruption.

Common situations: Pointing Export at the wrong SQLite file (another app's database); a legacy database predating the version-marker convention; manual edits or corruption that removed the metadata row; an already-migrated/truncated database.

Related errors

• clone from %s succeeded, but the database needs %d schema %s
• unsupported legacy SQLite release %q
• legacy SQLite schema drift in %s hidden column
• legacy SQLite schema drift in %s
• legacy SQLite issue %s uses unsupported removed fields

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