gastownhall/beads · error

unsupported legacy SQLite release %q

Error message

unsupported legacy SQLite release %q

What it means

After reading bd_version from the metadata table, verify() checks it against acceptedVersions, an explicit allow-list (currently {"0.49.6","0.50.3"}). Any other value — older or newer bd releases, or garbage — yields 'unsupported legacy SQLite release %q'. The package migrates only exact, audited contracts, so unknown releases are rejected rather than guessed at.

Source

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

	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 {
	rows, err := db.QueryContext(ctx, "PRAGMA table_xinfo("+table+")")
	if err != nil {
		return err

View on GitHub (pinned to 71377f2769)

Solutions

  1. Check the version: sqlite3 beads.db "SELECT value FROM metadata WHERE key='bd_version'" and compare with the accepted list for this build
  2. Use a bd release whose acceptedVersions includes your database's version to run the migration
  3. If on a newer version, first migrate intermediate steps with the appropriate older bd release, or wait for/upgrade to a build that accepts it
  4. If the value looks corrupted, restore the database from backup

Example fix

$ sqlite3 beads.db "SELECT value FROM metadata WHERE key='bd_version';"
0.48.2
// error: unsupported legacy SQLite release "0.48.2"
// fix: run the migration with a bd release that accepts 0.48.2 (e.g. bd 0.49.x) first,
// or upgrade the database through the intermediate supported versions
Defensive patterns

Strategy: validation

Validate before calling

// pre-flight: check bd_version against your build's accepted list
func checkAcceptedVersion(dbPath string, accepted map[string]bool) error {
	db, err := sql.Open("sqlite3", dbPath+"?mode=ro"); if err != nil { return err }
	defer db.Close()
	var v string
	if err := db.QueryRow("SELECT value FROM metadata WHERE key='bd_version'").Scan(&v); err != nil { return err }
	if !accepted[v] { return fmt.Errorf("bd_version %q not accepted by this build; use a matching bd release", v) }
	return nil
}

Try / catch

if err := legacysqlite.Export(ctx, src, out, os.Stdout); err != nil {
	if strings.Contains(err.Error(), "unsupported legacy SQLite release") {
		return fmt.Errorf("run the migration with the bd release matching the database version (see metadata.bd_version)")
	}
	return err
}

Prevention

When it happens

Trigger: Export -> read -> verify where the metadata bd_version value is not in acceptedVersions — e.g. version "0.48.2", a future version like "0.51.0", or an empty/corrupted marker string.

Common situations: Migrating a database produced by a much older or newer bd release than this binary supports; a hand-edited metadata table; upgrading bd before finishing migration of old repos.

Related errors

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