{"record":{"id":"0e4f6615c6961ea6","repo":"gastownhall/beads","slug":"uow-failed-to-start-transaction-w","errorCode":null,"errorMessage":"uow: failed to start transaction: %w","messagePattern":"uow: failed to start transaction: %w","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"internal/storage/uow/dolt_sql_provider.go","lineNumber":152,"sourceCode":"func (p *doltSQLProvider) Close(ctx context.Context) error {\n\tif p.db == nil {\n\t\treturn nil\n\t}\n\tdb := p.db\n\tp.db = nil\n\treturn db.Close()\n}\n\nfunc (p *doltSQLProvider) BeginTx(ctx context.Context) (Tx, error) {\n\tconn, err := p.db.Conn(ctx)\n\tif err != nil {\n\t\treturn nil, fmt.Errorf(\"uow: pin connection: %w\", err)\n\t}\n\n\t_, err = conn.ExecContext(ctx, \"START TRANSACTION;\")\n\tif err != nil {\n\t\t_ = conn.Close()\n\t\treturn nil, fmt.Errorf(\"uow: failed to start transaction: %w\", err)\n\t}\n\n\t// Bind journal activation to the connection this unit of work is pinned to,\n\t// AFTER START TRANSACTION so the seq allocation's UPDATE and the SELECT that\n\t// must observe it are inside one transaction on one session. The scope is\n\t// released when the connection is (doltServerTx.releaseConn / poisonConn),\n\t// so an entry cannot outlive its transaction.\n\treturn &doltServerTx{\n\t\tconn:              conn,\n\t\tclearJournalScope: issueops.ScopeEventsJournalTransaction(conn, p.eventsJournalEnabled.Load()),\n\t}, nil\n}\n\n// selectProbeDatabase lets schema's pre-lock convergence probe reach the\n// database on a session that is not yet on one. openAndInitSchema pins its\n// schema-init pool with an EMPTY DSN database, so without this the probe reads\n// NULL from DATABASE(), declines, and every invocation queues on the\n// server-wide migration lock it exists to skip.","sourceCodeStart":134,"sourceCodeEnd":170,"githubUrl":"https://github.com/gastownhall/beads/blob/71377f276968b452ee607177637970a4ff888584/internal/storage/uow/dolt_sql_provider.go#L134-L170","documentation":"After pinning a connection, BeginTx executes 'START TRANSACTION;' on it. If that statement fails, the connection is closed and this error wraps the cause as 'uow: failed to start transaction: %w'.","triggerScenarios":"conn.ExecContext(ctx, \"START TRANSACTION;\") returns an error: the server dropped the connection, the context was canceled mid-statement, or the session is in a state that refuses a new transaction (e.g. an implicit transaction already open on that pinned session).","commonSituations":"Dolt server restart or idle timeout killing the pinned connection between Conn() and START TRANSACTION; network interruption; ctx deadline expiring exactly during transaction start.","solutions":["Retry the unit of work — pool connections are refreshed automatically after a dropped session.","Increase the context timeout if START TRANSACTION is racing the deadline.","Check Dolt server logs for session kills or restarts at the failure time.","Verify no proxy/idle timeout (defaultProxyIdleTimeout) is reaping connections mid-open."],"exampleFix":"// before\nuow, err := provider.NewUOW(ctx) // one short ctx reused everywhere\n\n// after\nctx, cancel := context.WithTimeout(context.Background(), 30*time.Second)\ndefer cancel()\nuow, err := provider.NewUOW(ctx)\nif err != nil {\n    var retryable bool // serialization errors surface similarly\n    _ = retryable\n    return err\n}","handlingStrategy":"retry","validationCode":"// health-check the server before starting transactions\nif err := db.PingContext(ctx); err != nil {\n    return fmt.Errorf(\"dolt server not ready for transactions: %w\", err)\n}","typeGuard":null,"tryCatchPattern":"tx, err := provider.BeginTx(ctx)\nif err != nil {\n    if strings.Contains(err.Error(), \"failed to start transaction\") {\n        // connection likely dropped between Conn() and START TRANSACTION — safe to retry once\n        return retryOnce(ctx, provider.BeginTx)\n    }\n    return err\n}","preventionTips":["Keep contexts generous relative to network latency to the server.","Raise proxy idle timeouts if the server reaps idle sessions mid-open.","Treat any server restart as invalidating in-flight transactions; retry from scratch.","Monitor server logs for 'server has gone away' style kills."],"tags":["database","transaction","network"],"backgroundTag":"transaction-start-failed","analyzedSha":"71377f276968b452ee607177637970a4ff888584","analyzedAt":"2026-08-30T18:55:39.744Z","schemaVersion":2},"datasetVersion":"2026-08-30T23:17:21.991Z"}