{"record":{"id":"1845ba4e914899c2","repo":"gastownhall/beads","slug":"ensuring-local-metadata-w","errorCode":null,"errorMessage":"ensuring local_metadata: %w","messagePattern":"ensuring local_metadata: %w","errorType":"console","errorClass":null,"httpStatus":null,"severity":"error","filePath":"internal/storage/schema/aux_row_id_backfill.go","lineNumber":121,"sourceCode":"\t\tkeys[i] = pass.sentinelKey\n\t}\n\tvar n int\n\tif err := db.QueryRowContext(ctx,\n\t\tfmt.Sprintf(\"SELECT COUNT(*) FROM local_metadata WHERE `key` IN (%s)\", strings.Join(placeholders, \", \")),\n\t\tkeys...).Scan(&n); err != nil {\n\t\treturn false, err\n\t}\n\treturn n > 0, nil\n}\n\nfunc setAuxRekeyInProgress(ctx context.Context, db DBConn, sentinelKey string) error {\n\t// local_metadata is dolt-ignored, hence clone-local: a fresh clone whose\n\t// main cursor is already past 0029 does not have the table (the migration\n\t// will not re-run) until EnsureIgnoredTables recreates it. Create it here\n\t// with 0029's DDL — its dolt_ignore pattern is committed history, so the\n\t// sentinel stays clone-local.\n\tif _, err := db.ExecContext(ctx, \"CREATE TABLE IF NOT EXISTS local_metadata (`key` VARCHAR(255) PRIMARY KEY, value TEXT NOT NULL DEFAULT '')\"); err != nil {\n\t\treturn fmt.Errorf(\"ensuring local_metadata: %w\", err)\n\t}\n\t_, err := db.ExecContext(ctx,\n\t\t\"REPLACE INTO local_metadata (`key`, value) VALUES (?, '1')\",\n\t\tsentinelKey)\n\treturn err\n}\n\nfunc clearAuxRekeyInProgress(ctx context.Context, db DBConn, sentinelKey string) error {\n\t_, err := db.ExecContext(ctx,\n\t\t\"DELETE FROM local_metadata WHERE `key` = ?\",\n\t\tsentinelKey)\n\treturn err\n}\n\n// auxRekeyTable describes one table covered by the re-key. columns is the\n// frozen SELECT list of every non-id column, in creation order, with datetime\n// columns CAST to CHAR server-side so the scanned text is identical across\n// drivers and connection settings.","sourceCodeStart":103,"sourceCodeEnd":139,"githubUrl":"https://github.com/gastownhall/beads/blob/71377f276968b452ee607177637970a4ff888584/internal/storage/schema/aux_row_id_backfill.go#L103-L139","documentation":"setAuxRekeyInProgress records the clone-local crash sentinel for an aux-row rekey pass in the dolt-ignored local_metadata table. Because local_metadata is dolt-ignored, a fresh clone whose main migration cursor is already past migration 0029 does not have the table, so this function first runs CREATE TABLE IF NOT EXISTS with 0029's DDL. This error wraps any failure of that CREATE TABLE, meaning the sentinel could not be laid down and the rekey rewrite has not started.","triggerScenarios":"Running MigrateUp on a fresh or partially-synced Dolt clone where local_metadata is missing and the CREATE TABLE IF NOT EXISTS statement fails — typically due to connection loss, permissions (no CREATE privilege), read-only replica, or a conflicting object named local_metadata.","commonSituations":"Upgrading a cloned beads repository (bd pull/clone then run) where the ignored table has not been recreated by EnsureIgnoredTables; running with a DB user lacking DDL privileges; a crashed/terminated earlier migration leaving locks; storage-backend version mismatch.","solutions":["Unwrap and read the driver error — check connectivity and re-run; the pass is resumable and the rewrite has not started.","Grant the database user CREATE privilege (or run migrations as an admin) so local_metadata can be created.","Check for a conflicting non-ignored object named local_metadata and drop/rename it.","Run `bd doctor` / re-open the database to let EnsureIgnoredTables recreate dolt-ignored tables, then retry MigrateUp."],"exampleFix":"// before\n// app user lacks DDL rights; CREATE TABLE IF NOT EXISTS local_metadata fails\n\n// after\n-- as admin, once per clone:\nCREATE TABLE IF NOT EXISTS local_metadata (`key` VARCHAR(255) PRIMARY KEY, value TEXT NOT NULL DEFAULT '');\nGRANT CREATE ON mydb.* TO 'beads'@'%';","handlingStrategy":"retry","validationCode":"// before migrating, verify the clone can create the ignored table:\nvar canCreate int\n_ = db.QueryRow(`SELECT COUNT(*) FROM INFORMATION_SCHEMA.SCHEMA_PRIVILEGES\n WHERE TABLE_SCHEMA = DATABASE() AND PRIVILEGE_TYPE = 'CREATE'`).Scan(&canCreate)\nif canCreate == 0 { return errors.New(\"migration user cannot CREATE local_metadata\") }","typeGuard":null,"tryCatchPattern":"if err := runMigration(); err != nil {\n    if strings.Contains(err.Error(), \"ensuring local_metadata\") {\n        return fmt.Errorf(\"storage unavailable or lacking DDL privilege; fix and re-run migration (resumable): %w\", err)\n    }\n    return err\n}","preventionTips":["Run migrations with a user holding CREATE and INSERT privileges.","Never delete dolt-ignored tables (local_metadata) by hand — they are clone-local state.","Run bd doctor after cloning to recreate ignored tables before the first migration.","Avoid concurrent bd processes on the same clone during migrations."],"tags":["database","migration","dolt","sentinel"],"backgroundTag":"migration-sentinel-write-failed","analyzedSha":"71377f276968b452ee607177637970a4ff888584","analyzedAt":"2026-08-30T18:55:39.744Z","schemaVersion":2},"datasetVersion":"2026-08-30T23:17:21.991Z"}