What causes "check staged changes before commit: %w" in gastownhall/beads?

Retry the operation; nothing was committed so a retry is safe.

check staged changes before commit: %w

Error message

check staged changes before commit: %w

What it means

The pre-commit guard HasStagedChanges failed, so the store cannot tell whether anything is staged and aborts with a plain error (deliberately NOT marked as a publication failure, since nothing was committed yet).

Source

Thrown at internal/storage/dolt/store.go:3311

		defer conn.Close()

		for _, table := range tables {
			if err := schema.DrainCall(ctx, conn, "CALL DOLT_ADD(?)", table); err != nil {
				return s.recordDoltPublicationFailure(ctx,
					fmt.Errorf("dolt add %s after SQL mutation: %w: %w", table, err, ErrCommitIndeterminate))
			}
		}

		// Skip the commit when nothing was actually staged (idempotent no-op
		// write), so Dolt does not log a server-side "nothing to commit" warning
		// on every reconcile-cadence call. The guard tests the STAGED set rather
		// than the whole working set because this helper stages only a fixed
		// table list — an unrelated dirty table must not trigger an empty '-m'
		// commit. A guard-read failure is NOT a publication failure: nothing has
		// been committed and nothing is indeterminate, so plain error return.
		staged, err := issueops.HasStagedChanges(ctx, conn)
		if err != nil {
			return fmt.Errorf("check staged changes before commit: %w", err)
		}
		if !staged {
			return nil
		}

		if err := schema.DrainCall(ctx, conn, "CALL DOLT_COMMIT('-m', ?, '--author', ?)",
			commitMsg, s.commitAuthorString()); err != nil && !isDoltNothingToCommit(err) {
			return s.recordDoltPublicationFailure(ctx,
				fmt.Errorf("dolt commit after SQL mutation: %w: %w", err, ErrCommitIndeterminate))
		}
		return nil
	})
}

func (s *DoltStore) wrapDoltPublicationFailure(ctx context.Context, op string, err error) error {
	return s.recordDoltPublicationFailure(ctx, wrapSQLCommitError(op, err))
}

View on GitHub (pinned to 71377f2769)

Solutions

Retry the operation; nothing was committed so a retry is safe.
Verify server connectivity (bd dolt status).
Inspect the wrapped cause (%w) for the specific query error and address it (permissions, schema).

Defensive patterns

Strategy: retry

Validate before calling

// safe to retry: nothing was committed; confirm DB is queryable first
if err := s.db.PingContext(ctx); err != nil {
    return fmt.Errorf("database unavailable: %w", err)
}

Try / catch

if strings.Contains(err.Error(), "check staged changes before commit") {
    // plain failure, no indeterminacy: safe to retry the operation
}

Prevention

Ensure the database user has permission to read dolt_status.
Retry transient read failures automatically with backoff.
Keep bd version aligned with the database schema.
Monitor server health during reconcile-cadence commits.

When it happens

Trigger: doltAddAndCommit runs its staged-changes guard query and the query errors — connection drop, permission issue, or failure reading dolt_status internally.

Common situations: Transient Dolt server error during reconcile-cadence commits; database permission problems; schema change to dolt_status internals.

Related errors

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