{"record":{"id":"5f4f855f9b0315d5","repo":"gastownhall/beads","slug":"failed-to-initialize-schema-w","errorCode":null,"errorMessage":"failed to initialize schema: %w","messagePattern":"failed to initialize schema: %w","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"critical","filePath":"internal/storage/dolt/store.go","lineNumber":2026,"sourceCode":"\t\tvar verifyErr error\n\t\tif cfg.Database == doltserver.GlobalDatabaseName {\n\t\t\tverifyErr = store.verifyGlobalProjectIdentity(ctx, cfg.BeadsDir)\n\t\t} else {\n\t\t\tverifyErr = store.verifyProjectIdentity(ctx, cfg.BeadsDir)\n\t\t}\n\t\tif verifyErr != nil {\n\t\t\treturn nil, verifyErr\n\t\t}\n\t}\n\n\t// A gateway server owns the schema: it provisions each project at its deployed bd\n\t// version, so a client must never run migrations (DDL) against it. Treat it like\n\t// ReadOnly for schema — the forward-drift guard above still protects a stale client\n\t// binary.\n\tif !cfg.ReadOnly && !cfg.Gateway {\n\t\tapplied, err := store.initSchema(ctx, dbFacts.bootstrapHeal)\n\t\tif err != nil {\n\t\t\treturn nil, fmt.Errorf(\"failed to initialize schema: %w\", err)\n\t\t}\n\t\t// initSchema runs migrations over a separate pool (openMigrationDB).\n\t\t// The Ping above already pinned a connection in store.db to the\n\t\t// pre-migration session root; without a rebuild, the first read\n\t\t// through that stale connection returns 0 rows / table-not-found\n\t\t// and does not self-heal on retry (be-itm5). Only a migrating open\n\t\t// (applied > 0) needs this — rebuildPoolAfterMigration no-ops otherwise.\n\t\tif err := store.rebuildPoolAfterMigration(ctx, applied); err != nil {\n\t\t\treturn nil, fmt.Errorf(\"failed to rebuild pool after migration: %w\", err)\n\t\t}\n\t}\n\n\tif isLocalHost(cfg.ServerHost) {\n\t\tbeadsDir := cfg.BeadsDir\n\t\tif beadsDir == \"\" && cfg.Path != \"\" {\n\t\t\tbeadsDir = filepath.Dir(cfg.Path)\n\t\t}\n\t\t_ = persistResolvedPortFile(cfg, beadsDir)","sourceCodeStart":2008,"sourceCodeEnd":2044,"githubUrl":"https://github.com/gastownhall/beads/blob/71377f276968b452ee607177637970a4ff888584/internal/storage/dolt/store.go#L2008-L2044","documentation":"This error wraps a failure from store.initSchema during DoltStore open. It means schema migrations (DDL) could not be applied, so the store cannot guarantee the expected table layout. It is thrown at open time for non-ReadOnly, non-Gateway configs. The wrapped err carries the root cause (migration SQL failure, connection drop, drift guard).","triggerScenarios":"Opening a DoltStore with cfg.ReadOnly=false and cfg.Gateway=false where store.initSchema(ctx, dbFacts.bootstrapHeal) returns an error — e.g. a migration SQL statement fails, the migrations table can't be written, or a bootstrap-heal step fails.","commonSituations":"Server restarted mid-migration leaving partial DDL; stale client binary against a newer schema (version drift); MySQL/Dolt server rejecting DDL due to permissions; network interruption during DDL.","solutions":["Read the wrapped err to identify the failing migration step","Verify the Dolt server is running and reachable (bd dolt status)","Check the DB user has DDL privileges","Upgrade or align the bd client binary with the server schema version","If drift/partial migration is suspected, restore from backup or let a healthy client run migrations"],"exampleFix":"// before\nstore, err := NewStore(ctx, cfg) // opaque failure\n// after\nstore, err := NewStore(ctx, cfg)\nif err != nil {\n    var initErr *fmt.WrapError // inspect wrapped initSchema error\n    log.Fatalf(\"schema init failed: %v\", err)\n}","handlingStrategy":"retry","validationCode":"if cfg.ReadOnly || cfg.Gateway { skip schema init } // else ensure server reachable first:\nif err := db.PingContext(ctx); err != nil { return fmt.Errorf(\"server unreachable before schema init: %w\", err) }","typeGuard":null,"tryCatchPattern":"store, err := NewStore(ctx, cfg)\nif err != nil {\n    if strings.Contains(err.Error(), \"failed to initialize schema\") {\n        // inspect wrapped cause, verify server, retry once\n    }\n    return err\n}","preventionTips":["Keep client binary and server schema versions aligned","Ensure DB user has DDL privileges","Monitor server uptime during deploys","Back up .beads before major version upgrades"],"tags":["database","schema","migration","dolt"],"backgroundTag":"schema-migration-failed","analyzedSha":"71377f276968b452ee607177637970a4ff888584","analyzedAt":"2026-08-30T18:55:39.744Z","schemaVersion":2},"datasetVersion":"2026-08-30T23:17:21.991Z"}