gastownhall/beads · error

failed to begin transaction: %w

Error message

failed to begin transaction: %w

What it means

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.

Source

Thrown at cmd/bd/doctor/fix/validation.go:85

			orphans = append(orphans, o)
		}
	}
	if err := rows.Err(); err != nil {
		return fmt.Errorf("row iteration error: %w", err)
	}

	if len(orphans) == 0 {
		fmt.Println("  No orphaned dependencies to fix")
		return nil
	}

	// Delete orphaned dependencies
	// Uses explicit transaction so writes persist when @@autocommit is OFF
	// (e.g. Dolt server started with --no-auto-commit).
	showIndividual := verbose || len(orphans) < 20
	tx, err := db.Begin()
	if err != nil {
		return fmt.Errorf("failed to begin transaction: %w", err)
	}
	var removed int
	for _, o := range orphans {
		var err error
		switch o.depTable {
		case "dependencies":
			_, err = tx.Exec("DELETE FROM dependencies WHERE issue_id = ? AND "+fixDependencyTargetExpr+" = ?", o.issueID, o.dependsOnID)
		case "wisp_dependencies":
			_, err = tx.Exec("DELETE FROM wisp_dependencies WHERE issue_id = ? AND "+fixDependencyTargetExpr+" = ?", o.issueID, o.dependsOnID)
		default:
			fmt.Printf("  Warning: skipped orphaned dependency from unexpected table %s\n", o.depTable)
			continue
		}
		if err != nil {
			fmt.Printf("  Warning: failed to remove %s→%s: %v\n", o.issueID, o.dependsOnID, err)
		} else {
			removed++
			if showIndividual {

View on GitHub (pinned to 71377f2769)

Solutions

1. Confirm the Dolt server is running and healthy, then re-run the fix.
2. Check the wrapped driver error for 'bad connection' or 'connection refused' and address connectivity first.
3. Avoid running doctor --fix concurrently with other long-lived sessions that may lock or exhaust connections.
4. If Begin failures persist on an embedded/local database, restart the Dolt server process to get a clean session.

Example fix

// before
if skip, err := guardFixTarget("Orphaned dependencies fix", db, beadsDir, cfg); skip {
	return err
}
tx, err := db.Begin()
if err != nil {
	return fmt.Errorf("failed to begin transaction: %w", err)
}
// after: verify server alive before attempting writes
// dolt server status  # ensure it is up
tx, err := db.Begin()
if err != nil {
	return fmt.Errorf("failed to begin transaction: %w", err) // succeeds on healthy server
}

// ensure the server accepts a transaction before starting the fix
if err := db.PingContext(ctx); err != nil {
	return fmt.Errorf("database not accepting sessions: %w", err)
}

var sqlErr *driver.Error
if errors.As(err, &sqlErr) {
	// inspect sqlErr.Number to distinguish shutdown/locked from generic failure
}

if err := fix.OrphanedDependencies(path, verbose); err != nil {
	if strings.Contains(err.Error(), "failed to begin transaction") {
		// server side issue: check server status, restart, then retry
		restartDoltServer()
		err = fix.OrphanedDependencies(path, verbose)
	}
	if err != nil {
		log.Fatalf("orphan fix aborted before writes: %v", err)
	}
}

When it happens

Trigger: 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).

Common situations: 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.

Related errors

• ErrTransaction
• failed to begin transaction: %w
• failed to commit is_blocked repairs: %w
• failed to commit orphaned dependency removals: %w
• ErrQuery

AI-assisted analysis of gastownhall/beads@71377f2769 (2026-08-30). Data as JSON: /api/errors/a197f8e13e4f991e. Report an issue: GitHub.