{"record":{"id":"34bf28101e027428","repo":"gastownhall/beads","slug":"legacy-sqlite-release-marker-w","errorCode":null,"errorMessage":"legacy SQLite release marker: %w","messagePattern":"legacy SQLite release marker: %w","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"internal/migration/legacysqlite/reader.go","lineNumber":309,"sourceCode":"\tif err := loadChildren(ctx, tx, issues); err != nil {\n\t\treturn err\n\t}\n\tif err := tx.Commit(); err != nil {\n\t\treturn err\n\t}\n\tenc := json.NewEncoder(out)\n\tfor _, issue := range issues {\n\t\tif err := enc.Encode(issue); err != nil {\n\t\t\treturn err\n\t\t}\n\t}\n\treturn nil\n}\n\nfunc verify(ctx context.Context, db *sql.Tx) error {\n\tvar version string\n\tif err := db.QueryRowContext(ctx, \"SELECT value FROM metadata WHERE key = 'bd_version'\").Scan(&version); err != nil {\n\t\treturn fmt.Errorf(\"legacy SQLite release marker: %w\", err)\n\t}\n\tif !acceptedVersions[version] {\n\t\treturn fmt.Errorf(\"unsupported legacy SQLite release %q\", version)\n\t}\n\tfor table, want := range schema {\n\t\tif err := verifyTable(ctx, db, table, want); err != nil {\n\t\t\treturn err\n\t\t}\n\t}\n\tfor _, table := range []string{\"metadata\", \"issues\", \"dependencies\", \"labels\", \"comments\"} {\n\t\tif err := verifyFKs(ctx, db, table); err != nil {\n\t\t\treturn err\n\t\t}\n\t}\n\treturn nil\n}\n\nfunc verifyTable(ctx context.Context, db *sql.Tx, table, want string) error {","sourceCodeStart":291,"sourceCodeEnd":327,"githubUrl":"https://github.com/gastownhall/beads/blob/71377f276968b452ee607177637970a4ff888584/internal/migration/legacysqlite/reader.go#L291-L327","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["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\")","If the database predates the marker, open it with the matching old bd release first and let it upgrade/re-export","If the metadata table is missing/corrupt, restore the database from backup","Run PRAGMA integrity_check to rule out corruption before retrying"],"exampleFix":"// inspect the source before exporting\n$ sqlite3 beads.db \"SELECT key, value FROM metadata;\"\n-- if this errors with 'no such table: metadata', this is not a beads legacy DB\n$ bd migrate --legacy ./correct/beads.db --output issues.jsonl","handlingStrategy":"validation","validationCode":"// pre-flight: confirm the file is a recognized legacy beads database\nfunc hasVersionMarker(dbPath string) (string, error) {\n\tdb, err := sql.Open(\"sqlite3\", dbPath+\"?mode=ro\"); if err != nil { return \"\", err }\n\tdefer db.Close()\n\tvar v string\n\terr = db.QueryRow(\"SELECT value FROM metadata WHERE key = 'bd_version'\").Scan(&v)\n\treturn v, err\n}","typeGuard":null,"tryCatchPattern":"if err := legacysqlite.Export(ctx, src, out, os.Stdout); err != nil {\n\tvar se *string // inspect wrapped cause\n\tif strings.Contains(err.Error(), \"legacy SQLite release marker\") {\n\t\treturn fmt.Errorf(\"%s is not a recognized legacy beads DB (missing bd_version); check the path\", src)\n\t}\n\treturn err\n}","preventionTips":["Verify the source with sqlite3 before migrating: SELECT value FROM metadata WHERE key='bd_version'","Double-check the path points at the legacy beads database, not another app's SQLite file","Keep backups; a missing marker often means the wrong or corrupted file","If the DB predates the marker, use the matching old bd release to upgrade it first"],"tags":["sqlite","migration","schema","versioning"],"backgroundTag":"missing-version-marker","analyzedSha":"71377f276968b452ee607177637970a4ff888584","analyzedAt":"2026-08-30T18:55:39.744Z","schemaVersion":2},"datasetVersion":"2026-08-30T23:17:21.991Z"}