What causes "commit pending before pull: %w" in gastownhall/beads?

Inspect the wrapped cause: if it is ErrCommitIndeterminate, first read the current state/HEAD to see whether the pre-commit actually landed before retrying.

gastownhall/beads · error

commit pending before pull: %w

Error message

commit pending before pull: %w

What it means

EmbeddedDoltStore.Pull auto-commits pending working-set changes before pulling (GH#2474 / bd-578h9.2), because leftovers from a crashed command would make the incoming merge refuse to start. This error wraps any failure from that pre-pull CommitPending call — the pull itself was never attempted. The wrapped error carries the underlying commit failure (which may itself be ErrCommitIndeterminate).

Source

Thrown at internal/storage/embeddeddolt/version_control.go:528

// unchanged. Routing every verb through the one resolver also narrows the
// window around withPeerAuth's mutation of that process-wide pair: a verb
// operating on a peer-backed remote now reads it holding federationEnvMutex,
// where before it read it holding no lock at all.

func (s *EmbeddedDoltStore) Push(ctx context.Context) error {
	return s.withPeerAuth(ctx, defaultRemote, func(user string) error {
		return s.withMutatingDBConn(ctx, func(db versioncontrolops.DBConn) error {
			return vcPush(ctx, db, defaultRemote, s.branch, user)
		})
	})
}

func (s *EmbeddedDoltStore) Pull(ctx context.Context) error {
	// GH#2474 / bd-578h9.2: auto-commit pending changes before pull, matching
	// server-mode pullFromRemote and PullFrom. Leftovers from a crashed
	// command would otherwise make the merge refuse to start.
	if _, err := s.CommitPending(ctx, "beads"); err != nil {
		return fmt.Errorf("commit pending before pull: %w", err)
	}
	preHead := s.preMergeHead(ctx)
	err := s.withPeerAuth(ctx, defaultRemote, func(user string) error {
		return s.withMutatingPinnedDBConn(ctx, func(db versioncontrolops.DBConn) error {
			return vcPull(ctx, db, defaultRemote, s.branch, user)
		})
	})
	if err != nil {
		return err
	}
	return s.recomputeBlockedAfterPull(ctx, preHead)
}

// PullWithStrategy implements storage.StrategicPuller for `bd dolt pull
// --strategy` (#4992 part 2). Identical to Pull except conflicts the
// auto-resolver declines are resolved with strategy instead of aborting the
// merge for the operator; see versioncontrolops.PullWithStrategy.
func (s *EmbeddedDoltStore) PullWithStrategy(ctx context.Context, strategy string) error {

View on GitHub (pinned to 71377f2769)

Solutions

Inspect the wrapped cause: if it is ErrCommitIndeterminate, first read the current state/HEAD to see whether the pre-commit actually landed before retrying.
Resolve any concurrent bd process holding the database, then retry the pull.
Run `bd doctor` if you suspect leftover state from a crashed command, then re-run `bd pull`.
Commit or stash the pending changes manually (bd commit / dolt status) and retry the pull.
If the database is corrupt, restore from remote or re-init the embedded store before pulling.

Example fix

// before: retrying pull immediately on error
if err := store.Pull(ctx); err != nil {
    return store.Pull(ctx)
}

// after: check indeterminate pre-commit state first
if err := store.Pull(ctx); err != nil {
    if errors.Is(err, storage.ErrCommitIndeterminate) {
        // pre-commit may have landed; verify then retry once
    }
    return err
}

Defensive patterns

Strategy: try-catch

Type guard

func isPrePullCommitFailure(err error) bool {
    return err != nil && strings.HasPrefix(err.Error(), "commit pending before pull:")
}

Try / catch

if err := store.Pull(ctx); err != nil {
    if isPrePullCommitFailure(err) {
        // failure is LOCAL auto-commit, not the remote pull.
        if errors.Is(err, storage.ErrCommitIndeterminate) {
            // verify local HEAD/state, reconcile, then retry once
        }
    }
    return err
}

Prevention

Commit or clean pending changes before pulling instead of relying solely on auto-commit.
Run one bd process per database; lock contention here means another writer is active.
After a crash, reconcile state (`bd doctor`) before pulling.
Handle ErrCommitIndeterminate explicitly — the pre-commit may have landed despite the error.

When it happens

Trigger: Calling Pull when CommitPending(ctx, "beads") fails — a Dolt commit error (driver failure, indeterminate commit, database locked/corrupt) occurs while auto-committing dirty tables before vcPull runs.

Common situations: Recovering after a crashed bd command left a dirty working set; database lock contention from a concurrent bd process; Dolt storage errors during the auto-commit; an indeterminate commit from a prior crash surfacing now.

Related errors

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