{"record":{"id":"2de992175acd9c0f","repo":"gastownhall/beads","slug":"errdanglingreference","errorCode":"ErrDanglingReference","errorMessage":"dangling chunk reference","messagePattern":"dangling chunk reference","errorType":"error_code","errorClass":null,"httpStatus":null,"severity":"critical","filePath":"internal/storage/dolt/errors.go","lineNumber":37,"sourceCode":"// with dolt-specific error types.\nvar (\n\t// ErrTransaction indicates a transaction begin/commit/rollback failure.\n\tErrTransaction = errors.New(\"transaction error\")\n\n\t// ErrQuery indicates a database query failure.\n\tErrQuery = errors.New(\"query error\")\n\n\t// ErrScan indicates a failure scanning database rows into Go values.\n\tErrScan = errors.New(\"scan error\")\n\n\t// ErrExec indicates a database exec (INSERT/UPDATE/DELETE) failure.\n\tErrExec = errors.New(\"exec error\")\n\n\t// ErrDanglingReference indicates that the pre-push integrity check detected\n\t// missing chunks in the local Dolt noms store. The push was aborted to\n\t// prevent propagating the corruption to the remote. Run bd dolt verify\n\t// to diagnose and recover.\n\tErrDanglingReference = errors.New(\"dangling chunk reference\")\n\n\t// ErrFSCKTimeout indicates that the pre-push integrity check (dolt fsck) did\n\t// not complete within the configured timeout. The push was aborted without\n\t// verifying chunk integrity — the store is not necessarily corrupt. Large\n\t// stores can be shrunk with `dolt gc` (or `CALL DOLT_GC()` on a running\n\t// sql-server); the timeout can be raised via the BEADS_FSCK_TIMEOUT\n\t// environment variable.\n\tErrFSCKTimeout = errors.New(\"pre-push integrity check timed out\")\n\n\t// ErrCommitIndeterminate is the storage-wide no-replay sentinel. Keep this\n\t// alias for server-Dolt callers while embedded Dolt returns the same value.\n\tErrCommitIndeterminate = storage.ErrCommitIndeterminate\n)\n\n// isTableNotExistError returns true if the error indicates a MySQL/Dolt\n// \"table doesn't exist\" error (error 1146). Used to distinguish legitimate\n// fallthrough (pre-migration databases without wisps table) from real errors\n// (timeouts, connection failures, corrupt data).","sourceCodeStart":19,"sourceCodeEnd":55,"githubUrl":"https://github.com/gastownhall/beads/blob/71377f276968b452ee607177637970a4ff888584/internal/storage/dolt/errors.go#L19-L55","documentation":"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.","triggerScenarios":"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.","commonSituations":"Machine crash or power loss during a write; corrupted disk; manually copying .dolt directories between machines; interrupted `dolt gc`; filesystem without proper fsync guarantees.","solutions":["Run `bd dolt verify` to confirm and localize the corruption.","Restore from a backup if available (.beads/backup/ JSONL or a prior clone).","Re-clone the remote and replay/reimport local unpushed data from JSONL exports.","Report persistent corruption; do not force-push, which would propagate corrupt chunks."],"exampleFix":"// before\nbd push  # aborts with dangling chunk reference\n// after\nbd dolt verify          # diagnose\nbd bootstrap            # or restore from backup, then re-push","handlingStrategy":"fallback","validationCode":"// detect before pushing\nif err := runDoltVerify(ctx); err != nil {\n    // store may contain dangling references; do not push\n}","typeGuard":null,"tryCatchPattern":"if errors.Is(err, dolt.ErrDanglingReference) {\n    // abort push, run bd dolt verify, restore from backup\n}","preventionTips":["Run bd dolt verify periodically on large stores","Avoid interrupting writes or `dolt gc`; use UPS","Maintain .beads/backup JSONL exports","Never force-push after integrity failures"],"tags":["dolt","corruption","integrity","push"],"backgroundTag":"dangling-chunk-reference","analyzedSha":"71377f276968b452ee607177637970a4ff888584","analyzedAt":"2026-08-30T18:55:39.744Z","schemaVersion":2},"datasetVersion":"2026-08-30T23:17:21.991Z"}