gastownhall/beads · error

begin tx: %w

Error message

begin tx: %w

What it means

AddComment fails when db.BeginTx cannot start a database transaction for the comment write. This means the connection to the Dolt backend is broken, the pool is exhausted, or the context was canceled before the transaction began. The underlying driver error is wrapped for errors.Is inspection.

Source

Thrown at internal/storage/dolt/events.go:20

import (
	"context"
	"database/sql"
	"fmt"
	"time"

	"github.com/steveyegge/beads/internal/storage"
	"github.com/steveyegge/beads/internal/storage/issueops"
	"github.com/steveyegge/beads/internal/types"
)

// AddComment adds a comment event to an issue
func (s *DoltStore) AddComment(ctx context.Context, issueID, actor, comment string) error {
	return s.withCircuitWrite(ctx, func(ctx context.Context) error {
		isWisp := s.isActiveWisp(ctx, issueID)
		tx, err := s.db.BeginTx(ctx, nil)
		if err != nil {
			return fmt.Errorf("begin tx: %w", err)
		}
		defer func() { _ = tx.Rollback() }()

		clearJournalScope := s.scopeEventsJournalTransaction(tx)
		defer clearJournalScope()

		if err := issueops.AddCommentEventInTx(ctx, tx, issueID, actor, comment); err != nil {
			return err
		}
		if err := s.commitSQLTx(ctx, "commit add comment event", tx); err != nil {
			return err
		}
		if isWisp {
			return nil
		}
		return s.doltAddAndCommit(ctx, []string{"events"}, fmt.Sprintf("bd: comment %s", issueID))
	})
}

View on GitHub (pinned to 71377f2769)

Solutions

1. Verify the Dolt backend is running (`bd doctor` or check dolt sql-server) and restart bd to rebuild the pool.
2. If the error is context.DeadlineExceeded, increase the timeout or check why the operation is slow.
3. Reduce concurrent bd processes/scripts writing to the same repo simultaneously.
4. If the database file path is wrong/unreachable, fix the config (storage path) and re-open.

Example fix

// before: no timeout on comment write
ctx := context.Background()
err := store.AddComment(ctx, issueID, actor, text)
// after: bounded context so begin-tx can't hang forever
ctx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
defer cancel()
err := store.AddComment(ctx, issueID, actor, text)

// Go: probe connectivity before comment writes
ctx, cancel := context.WithTimeout(context.Background(), 2*time.Second)
defer cancel()
if err := s.db.PingContext(ctx); err != nil {
	return fmt.Errorf("database unreachable: %w", err)
}

func IsBeginTxError(err error) bool {
	return err != nil && strings.Contains(err.Error(), "begin tx")
}

err := store.AddComment(ctx, issueID, actor, text)
if err != nil && strings.Contains(err.Error(), "begin tx") {
	// backend down or context canceled: reconnect and retry once
	time.Sleep(200 * time.Millisecond)
	return store.AddComment(ctx, issueID, actor, text)
}

When it happens

Trigger: Calling AddComment (bd comment/create flows) when the Dolt sql-server is not running, the connection pool was closed, the context deadline expired, or too many concurrent writers exhausted connections.

Common situations: Dolt server crashed or was restarted while a bd process was running; long-running bd command had its context canceled by the user; heavy parallel scripts opening many simultaneous writes; network/timeout to a remote Dolt server.

Related errors

• begin read tx: %w
• begin write tx: %w
• ErrTransaction
• failed to begin transaction: %w
• failed to commit is_blocked repairs: %w

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