{"record":{"id":"fd108d3c76d9dbba","repo":"gastownhall/beads","slug":"uow-bootstrap-preparation-w","errorCode":null,"errorMessage":"uow: bootstrap preparation: %w","messagePattern":"uow: bootstrap preparation: %w","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"warning","filePath":"internal/storage/uow/dolt_sql_provider.go","lineNumber":82,"sourceCode":"\ntype bootstrapPreparationError struct {\n\terr       error\n\tretryable bool\n}\n\nfunc (e *bootstrapPreparationError) Error() string {\n\treturn e.err.Error()\n}\n\nfunc (e *bootstrapPreparationError) Unwrap() error {\n\treturn e.err\n}\n\nfunc classifyInitSchemaError(err error) error {\n\tvar preparationErr *bootstrapPreparationError\n\tif errors.As(err, &preparationErr) {\n\t\tif preparationErr.retryable {\n\t\t\treturn fmt.Errorf(\"uow: bootstrap preparation: %w\", err)\n\t\t}\n\t\treturn backoff.Permanent(err)\n\t}\n\tif isSerializationError(err) || schema.IsMigrationLockError(err) {\n\t\treturn fmt.Errorf(\"uow: migrate: %w\", err)\n\t}\n\treturn backoff.Permanent(fmt.Errorf(\"uow: migrate: %w\", err))\n}\n\n// ProviderOption tunes how a SQL-server unit-of-work provider opens. Options\n// are variadic so the existing constructor call sites — every one of which\n// wants the ordinary mutating open — stay unchanged.\ntype ProviderOption func(*providerOptions)\n\ntype providerOptions struct {\n\t// preview opens for a command that promised not to mutate anything\n\t// (--dry-run, --inspect). Such a command must reach its own RunE before\n\t// anything writes, so the open may neither CREATE DATABASE nor run","sourceCodeStart":64,"sourceCodeEnd":100,"githubUrl":"https://github.com/gastownhall/beads/blob/71377f276968b452ee607177637970a4ff888584/internal/storage/uow/dolt_sql_provider.go#L64-L100","documentation":"classifyInitSchemaError wraps an error from schema migration as 'uow: bootstrap preparation' when the error is a bootstrapPreparationError flagged retryable. It marks a database bootstrap/prepare step (CREATE DATABASE, USE, pre-migration prep under the migration lock) that failed transiently and will be retried by the backoff loop. The wrapping keeps the preparation context on the error while letting backoff.Retry continue.","triggerScenarios":"During provider open, schema.MigrateUpWithLock's locked-preparation callback (bootstrapPreparer.prepare) returns a *bootstrapPreparationError with retryable=true; classifyInitSchemaError re-wraps it so the backoff retry in initSchema continues after the transient failure.","commonSituations":"Concurrent bd processes bootstrapping the same Dolt database at cold start; a peer holding the migration lock; brief connection blips to a loaded shared Dolt SQL server during CREATE DATABASE/USE.","solutions":["Retry is automatic: the initSchema backoff loop (60s budget) will re-attempt; simply re-run the command if the process exited.","Check that no other bd process is stuck holding the migration lock on the shared Dolt server.","Verify Dolt server connectivity and load; transient failures under load are the usual cause.","If it repeatedly fails, inspect the bootstrapPreparationError's wrapped cause for the underlying SQL error."],"exampleFix":null,"handlingStrategy":"retry","validationCode":"// ensure server reachable before opening the provider\nif err := db.PingContext(ctx); err != nil {\n    return fmt.Errorf(\"dolt server unreachable, bootstrap will retry: %w\", err)\n}","typeGuard":"var prepErr *uow.BootstrapPreparationError\nif errors.As(err, &prepErr) && prepErr.Retryable { /* transient: safe to retry */ }","tryCatchPattern":"err := provider.Open(ctx, cfg)\nif err != nil {\n    var prepErr *uow.BootstrapPreparationError\n    if errors.As(err, &prepErr) {\n        return retryWithBackoff(ctx, func() error { return provider.Open(ctx, cfg) })\n    }\n    return err\n}","preventionTips":["Avoid many concurrent cold starts against one fresh Dolt server.","Keep the migration-lock holder healthy; watchdog stuck migrations.","Give initSchema's backoff (60s) room: don't use sub-second contexts.","Monitor server load; bootstrap retries correlate with load spikes."],"tags":["database","retry","bootstrap","dolt"],"backgroundTag":"bootstrap-preparation-retryable","analyzedSha":"71377f276968b452ee607177637970a4ff888584","analyzedAt":"2026-08-30T18:55:39.744Z","schemaVersion":2},"datasetVersion":"2026-08-30T23:17:21.991Z"}