docs(readme): name the missing-parent-row cause behind a 23503 filler exit - #187
Merged
Merged
Conversation
There was a problem hiding this comment.
Pull request overview
Documents how to diagnose and recover from deferred foreign-key failures caused by incomplete AtomicAssets data.
Changes:
- Explains recurring
23503failures at COMMIT. - Adds schema-gap diagnostic queries.
- Recommends restoring a published dump.
💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.
robrigo
force-pushed
the
docs/orphan-base-row-troubleshooting
branch
from
August 21, 2026 23:49
f2cf7a5 to
092d855
Compare
… exit The three asset foreign keys that point at schemas, collections and templates are added NOT VALID, so orphaned asset rows already present when a constraint lands are never reported by the validation scan. They are also deferred, so the check that eventually runs happens at COMMIT and takes the whole block group with it. The result is a failure that surfaces years after the data gap opened, names a parent table the operator has no reason to suspect, and repeats identically on every restart, which reads as filler breakage rather than missing history. The entry gives the block-bucket comparison that separates a truncated history from a partial seed, and points at the dump restore rather than the row copy that only clears the current block. Signed-off-by: Rob Konsdorf <rob@facings.io>
robrigo
force-pushed
the
docs/orphan-base-row-troubleshooting
branch
from
August 21, 2026 23:54
092d855 to
6223f2f
Compare
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Why
An operator hit
23503onatomicassets_assets_schemas_fkeyat COMMIT and read it as a filler bug. It is not: the asset foreign keys shipDEFERRABLE INITIALLY DEFERRED NOT VALID, so a database seeded from an incomplete source carries orphaned asset rows that nothing ever validates. The violation surfaces only when a later block writes one of those assets, and it surfaces at COMMIT against a parent table the operator has no reason to suspect. Every restart replays the same block range and fails identically, so the failure reads as deterministic filler breakage rather than a data gap.The Troubleshooting section had no entry for this shape of failure, and the two facts an operator needs are both non-obvious: that
NOT VALIDmeans the gap can predate the running version by years, and that the fix is a restore rather than the row copy that clears only the current block.Validation
Documentation only, no code paths touched. Verified the entry against the code it describes: the five asset foreign keys carry
DEFERRABLE INITIALLY DEFERRED NOT VALIDindefinitions/tables/atomicassets_tables.sql, and every writer transaction issuesSET CONSTRAINTS ALL DEFERREDinsrc/filler/database.ts. Confirmed against a complete WAX database that the schema count is 80,416 and thatreconcileseeds v2 state and template deletions without rebuilding base rows. Checked the added lines for em-dash and smart quotes, and the#restore-from-a-published-dumpanchor resolves.