{"record":{"id":"15da97ce9218d3b9","repo":"gastownhall/beads","slug":"checking-schema-migration-work-w-15da97","errorCode":null,"errorMessage":"checking schema migration work: %w","messagePattern":"checking schema migration work: %w","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"internal/storage/schema/schema.go","lineNumber":577,"sourceCode":"func MigrateUpTo(ctx context.Context, db DBConn, maxVersion int) (int, error) {\n\tapplied, _, err := mainSource.migrate(ctx, db, maxVersion)\n\treturn applied, err\n}\n\nfunc MigrateUp(ctx context.Context, db DBConn) (int, error) {\n\t// Re-assert the canonical dolt_ignore patterns before anything else, and\n\t// in particular before the migrationWorkNeeded short-circuit: a database\n\t// whose migration cursors arrived at-latest without executing the seeding\n\t// migrations (out-of-band table copy) reports no work needed and\n\t// would otherwise never be healed.\n\tseedChanged, err := seedDoltIgnorePatterns(ctx, db)\n\tif err != nil {\n\t\treturn 0, err\n\t}\n\n\tneeded, err := migrationWorkNeeded(ctx, db)\n\tif err != nil {\n\t\treturn 0, fmt.Errorf(\"checking schema migration work: %w\", err)\n\t}\n\tif !needed {\n\t\t// No migration pass will run, so nothing downstream commits the seed:\n\t\t// it would sit as an uncommitted working-set diff until an unrelated\n\t\t// write/pull sweeps it into its commit (and a read-only repo carries\n\t\t// it indefinitely). Commit it here, scoped and labeled, so the\n\t\t// out-of-band-copy heal converges in one pass.\n\t\tif seedChanged {\n\t\t\tif err := commitSeededDoltIgnore(ctx, db); err != nil {\n\t\t\t\treturn 0, err\n\t\t\t}\n\t\t}\n\t\treturn 0, nil\n\t}\n\n\tdirtyBeforeAll, err := dirtyTables(ctx, db, false)\n\tif err != nil {\n\t\treturn 0, fmt.Errorf(\"reading pre-migration status: %w\", err)","sourceCodeStart":559,"sourceCodeEnd":595,"githubUrl":"https://github.com/gastownhall/beads/blob/71377f276968b452ee607177637970a4ff888584/internal/storage/schema/schema.go#L559-L595","documentation":"This error wraps a failure of `migrationWorkNeeded` — the pre-flight query that decides whether any schema migrations must run. MigrateUp calls it before doing any work so it can short-circuit and still commit seeded dolt_ignore patterns; failing here aborts the whole migration pass.","triggerScenarios":"Calling MigrateUp (directly or via MigrateUpWithLock) when the migration-work check queries schema state (current version vs. available migrations) and the underlying SQL fails — unreadable schema_migrations, locked working set, or context cancellation.","commonSituations":"Dolt server unavailable or restarting; concurrent bd process holding the migration or working-set lock; corrupt schema_migrations table; context deadline exceeded on slow networked Dolt.","solutions":["Inspect the wrapped cause for the underlying SQL failure","Ensure no other bd process is migrating concurrently (the advisory lock path serializes, but direct calls bypass it)","Verify schema_migrations is readable and the Dolt server is healthy","Retry MigrateUp once transient conditions clear"],"exampleFix":"// before: concurrent migrate calls collide\nerr := schema.MigrateUp(ctx, db)\n// after: use the locked wrapper\nerr := schema.MigrateUpWithLock(ctx, db)","handlingStrategy":"retry","validationCode":"// verify schema state is queryable before a migration pass\nif _, err := db.ExecContext(ctx, \"SELECT 1 FROM schema_migrations LIMIT 1\"); err != nil {\n\treturn fmt.Errorf(\"schema not queryable: %w\", err)\n}","typeGuard":null,"tryCatchPattern":"_, err := schema.MigrateUp(ctx, db)\nif err != nil && strings.Contains(err.Error(), \"checking schema migration work\") {\n\t// transient server/lock issue: back off and retry once\n\ttime.Sleep(backoff)\n\t_, err = schema.MigrateUpWithLock(ctx, db)\n}","preventionTips":["Prefer MigrateUpWithLock so concurrent processes serialize","Retry transient server errors with backoff","Check context deadlines — long networked Dolt reads can time out"],"tags":["migration","schema","pre-flight"],"backgroundTag":"migration-preflight-failed","analyzedSha":"71377f276968b452ee607177637970a4ff888584","analyzedAt":"2026-08-30T18:55:39.744Z","schemaVersion":2},"datasetVersion":"2026-08-30T23:17:21.991Z"}