What causes "pre-push integrity check timed out" in gastownhall/beads?

Raise the timeout: export BEADS_FSCK_TIMEOUT= and retry the push.

ErrFSCKTimeout

ErrFSCKTimeout

Error message

pre-push integrity check timed out

What it means

ErrFSCKTimeout indicates the pre-push integrity check (dolt fsck) did not finish within the configured timeout, so the push was aborted without verifying chunk integrity. The store is not necessarily corrupt — the check just ran out of time. Large stores can be shrunk with `dolt gc` (or `CALL DOLT_GC()` on a running sql-server), and the timeout raised via BEADS_FSCK_TIMEOUT.

Source

Thrown at internal/storage/dolt/errors.go:45

	// ErrScan indicates a failure scanning database rows into Go values.
	ErrScan = errors.New("scan error")

	// ErrExec indicates a database exec (INSERT/UPDATE/DELETE) failure.
	ErrExec = errors.New("exec error")

	// ErrDanglingReference indicates that the pre-push integrity check detected
	// missing chunks in the local Dolt noms store. The push was aborted to
	// prevent propagating the corruption to the remote. Run bd dolt verify
	// to diagnose and recover.
	ErrDanglingReference = errors.New("dangling chunk reference")

	// ErrFSCKTimeout indicates that the pre-push integrity check (dolt fsck) did
	// not complete within the configured timeout. The push was aborted without
	// verifying chunk integrity — the store is not necessarily corrupt. Large
	// stores can be shrunk with `dolt gc` (or `CALL DOLT_GC()` on a running
	// sql-server); the timeout can be raised via the BEADS_FSCK_TIMEOUT
	// environment variable.
	ErrFSCKTimeout = errors.New("pre-push integrity check timed out")

	// ErrCommitIndeterminate is the storage-wide no-replay sentinel. Keep this
	// alias for server-Dolt callers while embedded Dolt returns the same value.
	ErrCommitIndeterminate = storage.ErrCommitIndeterminate
)

// isTableNotExistError returns true if the error indicates a MySQL/Dolt
// "table doesn't exist" error (error 1146). Used to distinguish legitimate
// fallthrough (pre-migration databases without wisps table) from real errors
// (timeouts, connection failures, corrupt data).
func isTableNotExistError(err error) bool {
	return dberrors.IsTableNotExist(err)
}

// isBranchTrackingError returns true if the error indicates that DOLT_PULL
// failed because upstream branch tracking is not configured. This happens
// when a remote was added via DOLT_REMOTE('add') or bd dolt remote add
// rather than via dolt clone / bd bootstrap, leaving repo_state.json with

View on GitHub (pinned to 71377f2769)

Solutions

Raise the timeout: export BEADS_FSCK_TIMEOUT=<longer duration> and retry the push.
Shrink the store with `dolt gc` (or `CALL DOLT_GC()` on a running sql-server), then push again.
Run `bd dolt verify` separately to confirm integrity once the check can complete.
Move the store to faster local storage if on network disk.

Example fix

// before
bd push  # aborts: pre-push integrity check timed out
// after
export BEADS_FSCK_TIMEOUT=30m
dolt gc   # or: CALL DOLT_GC(); on sql-server
bd push

Defensive patterns

Strategy: retry

Validate before calling

// raise budget before pushing a large store
os.Setenv("BEADS_FSCK_TIMEOUT", "30m")

Try / catch

if errors.Is(err, dolt.ErrFSCKTimeout) {
    // retry with a larger BEADS_FSCK_TIMEOUT after dolt gc
}

Prevention

Set BEADS_FSCK_TIMEOUT proportionally to store size
Schedule `dolt gc` to keep the store small
Pre-verify with bd dolt verify before pushes in CI
Avoid network-attached slow disks for .beads storage

When it happens

Trigger: Pushing from a large or long-lived repository where dolt fsck exceeds BEADS_FSCK_TIMEOUT (default) before completing.

Common situations: Very large .beads history on an old project; slow disk (network storage); CI runner with tight default timeouts; store bloated after many unpruned GC cycles.

Understand the failure class

Timeouts: ETIMEDOUT, deadlines, and hung requests — what actually expires when a request times out.

Related errors

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