{"record":{"id":"a197f8e13e4f991e","repo":"gastownhall/beads","slug":"failed-to-begin-transaction-w-a197f8","errorCode":null,"errorMessage":"failed to begin transaction: %w","messagePattern":"failed to begin transaction: %w","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"cmd/bd/doctor/fix/validation.go","lineNumber":85,"sourceCode":"\t\t\torphans = append(orphans, o)\n\t\t}\n\t}\n\tif err := rows.Err(); err != nil {\n\t\treturn fmt.Errorf(\"row iteration error: %w\", err)\n\t}\n\n\tif len(orphans) == 0 {\n\t\tfmt.Println(\"  No orphaned dependencies to fix\")\n\t\treturn nil\n\t}\n\n\t// Delete orphaned dependencies\n\t// Uses explicit transaction so writes persist when @@autocommit is OFF\n\t// (e.g. Dolt server started with --no-auto-commit).\n\tshowIndividual := verbose || len(orphans) < 20\n\ttx, err := db.Begin()\n\tif err != nil {\n\t\treturn fmt.Errorf(\"failed to begin transaction: %w\", err)\n\t}\n\tvar removed int\n\tfor _, o := range orphans {\n\t\tvar err error\n\t\tswitch o.depTable {\n\t\tcase \"dependencies\":\n\t\t\t_, err = tx.Exec(\"DELETE FROM dependencies WHERE issue_id = ? AND \"+fixDependencyTargetExpr+\" = ?\", o.issueID, o.dependsOnID)\n\t\tcase \"wisp_dependencies\":\n\t\t\t_, err = tx.Exec(\"DELETE FROM wisp_dependencies WHERE issue_id = ? AND \"+fixDependencyTargetExpr+\" = ?\", o.issueID, o.dependsOnID)\n\t\tdefault:\n\t\t\tfmt.Printf(\"  Warning: skipped orphaned dependency from unexpected table %s\\n\", o.depTable)\n\t\t\tcontinue\n\t\t}\n\t\tif err != nil {\n\t\t\tfmt.Printf(\"  Warning: failed to remove %s→%s: %v\\n\", o.issueID, o.dependsOnID, err)\n\t\t} else {\n\t\t\tremoved++\n\t\t\tif showIndividual {","sourceCodeStart":67,"sourceCodeEnd":103,"githubUrl":"https://github.com/gastownhall/beads/blob/71377f276968b452ee607177637970a4ff888584/cmd/bd/doctor/fix/validation.go#L67-L103","documentation":"OrphanedDependencies opens an explicit transaction (db.Begin()) before deleting orphaned dependency rows, because Dolt servers can run with @@autocommit OFF (--no-auto-commit) where implicit writes would not persist. If db.Begin() fails, the fix is aborted with this wrapped error before any deletion happens.","triggerScenarios":"db.Begin() returns an error at validation.go:83 — typically the database connection is broken/closed, the driver cannot start a transaction on the current session, or the server refuses new transactions (shutting down, locked, or connection pool exhausted).","commonSituations":"Dolt server shutting down or restarted while `bd doctor --fix` runs; connection dropped between the earlier SELECT and Begin; server in a state that rejects transaction start (e.g. mid-shutdown, maintenance); driver-level issues after a long-running query consumed the connection.","solutions":["Confirm the Dolt server is running and healthy, then re-run the fix.","Check the wrapped driver error for 'bad connection' or 'connection refused' and address connectivity first.","Avoid running doctor --fix concurrently with other long-lived sessions that may lock or exhaust connections.","If Begin failures persist on an embedded/local database, restart the Dolt server process to get a clean session."],"exampleFix":"// before\nif skip, err := guardFixTarget(\"Orphaned dependencies fix\", db, beadsDir, cfg); skip {\n\treturn err\n}\ntx, err := db.Begin()\nif err != nil {\n\treturn fmt.Errorf(\"failed to begin transaction: %w\", err)\n}\n// after: verify server alive before attempting writes\n// dolt server status  # ensure it is up\ntx, err := db.Begin()\nif err != nil {\n\treturn fmt.Errorf(\"failed to begin transaction: %w\", err) // succeeds on healthy server\n}","handlingStrategy":"try-catch","validationCode":"// ensure the server accepts a transaction before starting the fix\nif err := db.PingContext(ctx); err != nil {\n\treturn fmt.Errorf(\"database not accepting sessions: %w\", err)\n}","typeGuard":"var sqlErr *driver.Error\nif errors.As(err, &sqlErr) {\n\t// inspect sqlErr.Number to distinguish shutdown/locked from generic failure\n}","tryCatchPattern":"if err := fix.OrphanedDependencies(path, verbose); err != nil {\n\tif strings.Contains(err.Error(), \"failed to begin transaction\") {\n\t\t// server side issue: check server status, restart, then retry\n\t\trestartDoltServer()\n\t\terr = fix.OrphanedDependencies(path, verbose)\n\t}\n\tif err != nil {\n\t\tlog.Fatalf(\"orphan fix aborted before writes: %v\", err)\n\t}\n}","preventionTips":["Don't run doctor --fix while the Dolt server is shutting down or under maintenance.","Limit concurrent bd sessions that hold long transactions on the same database.","Use a supervisor to keep the Dolt server alive for the duration of fixes.","Treat this error as safe-to-retry: it fires before any rows were modified."],"tags":["go","database","dolt","transaction"],"backgroundTag":"begin-transaction-failed","analyzedSha":"71377f276968b452ee607177637970a4ff888584","analyzedAt":"2026-08-30T18:55:39.744Z","schemaVersion":2},"datasetVersion":"2026-08-30T23:17:21.991Z"}