gastownhall/beads · critical

ErrDanglingReference

ErrDanglingReference

Error message

dangling chunk reference

What it means

ErrDanglingReference indicates the pre-push integrity check found missing chunks in the local Dolt noms store. The push was aborted so local corruption is not propagated to the remote. The docs advise running 'bd dolt verify' to diagnose and recover.

Source

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

// with dolt-specific error types.
var (
	// ErrTransaction indicates a transaction begin/commit/rollback failure.
	ErrTransaction = errors.New("transaction error")

	// ErrQuery indicates a database query failure.
	ErrQuery = errors.New("query error")

	// 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).

View on GitHub (pinned to 71377f2769)

Solutions

1. Run `bd dolt verify` to confirm and localize the corruption.
2. Restore from a backup if available (.beads/backup/ JSONL or a prior clone).
3. Re-clone the remote and replay/reimport local unpushed data from JSONL exports.
4. Report persistent corruption; do not force-push, which would propagate corrupt chunks.

Example fix

// before
bd push  # aborts with dangling chunk reference
// after
bd dolt verify          # diagnose
bd bootstrap            # or restore from backup, then re-push

// detect before pushing
if err := runDoltVerify(ctx); err != nil {
    // store may contain dangling references; do not push
}

if errors.Is(err, dolt.ErrDanglingReference) {
    // abort push, run bd dolt verify, restore from backup
}

When it happens

Trigger: Running bd push (or bd dolt push) when the local store's content-addressed chunk store is missing objects referenced by the root/value — typically after a crash mid-write, disk corruption, or an interrupted garbage collection.

Common situations: Machine crash or power loss during a write; corrupted disk; manually copying .dolt directories between machines; interrupted `dolt gc`; filesystem without proper fsync guarantees.

Related errors

• ErrFSCKTimeout
• dolt push failed: %w Output: %s
• failed to push to peer %s: %w
• push to %s/%s: %w
• force push to %s/%s: %w

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