Symptoms
The first command after an upgrade, or an explicitbd migrate schema, exits
1 with a refusal that names the migration it stopped in:
invalid hash length or
malformed out-of-band adaptive value. With --json, the same refusal is a
JSON error on stderr whose schema_encoding_drift object carries
migration, version, cursor_source, symptom and recovery_url. It
sits beside error and hint, inside data when BD_JSON_ENVELOPE=1.
The reported case
(gastownhall/beads#5699)
is migration 0035 on a store whose migration cursor predates it: 0035 stops
while it copies events rows. The refusal covers every numbered migration in
both migration series.
Before any further writes
The migration stopped on its first error and nothing was rolled back. Earlier migrations in the same pass may have completed, and partial changes may remain from the one that stopped. Leave the store as it is:- Stop every bd process, agent and script that uses the store.
- Preserve a full copy of the store and its configuration with the
whole-store preservation procedure,
keep the preserved copy outside any server
data_dir, and keep the original untouched as your fallback. The store is not always inside.beads:bd context --jsonshows where it lives. - Do not commit the working set, do not delete rows, and do not drop or reset tables to get past the error. Each of these can make unreadable values permanent or discard the evidence a recovery needs.
- A later run can stop before it reaches the migration, with
pending schema migrations alter pre-existing dirty tables: <tables>; run 'bd dolt commit' ...instead of this refusal. Those tables hold the stopped migration’s partial changes: for 0059,__bd_0059_recompute_wisp_deps,__bd_0059_recompute_wispsand, once its reset ran,issues. Do not runbd dolt commiton this store. It would record the half-applied migration in history, and a push would publish it. - Do not push from this store or pull into it until it is recovered.
Diagnosis
The refusal tells you which migration stopped and with what engine error. It does not tell you which table or row holds the unreadable value. The candidate tables are the ones that migration reads: theFROM, JOIN and ALTER TABLE
targets in the file it names, which you can find among the
migration files
(the ignored/ directory holds the ignored_schema_migrations series). Treat
them as candidate tables, not confirmed corruption locations. For example:
- 0035, the reported case: it copies infra rows into the wisp tables, and
reads
issues,labels,dependencies,eventsandcommentsto do it. The reported store stopped while 0035 copiedeventsrows intowisp_events, andeventsis where its unreadable text lives. Migrations 0057 and 0062 rewriteeventsas well. - 0059: it recomputes
is_blocked, and readsissues,dependencies,wispsandwisp_dependencies.
wisps and every wisp_* table) are clone-local: bd keeps
them out of Dolt history. From migration 0062 on, events is clone-local
too, and history keeps only the events rows written before it.
bd recognizes drift only by the error text the engine returns. It cannot
detect readable garbage: a value that decodes without an error but holds the
wrong content passes every read and every migration. A clean migration on a
recovered copy is therefore not proof that the data is correct (see
Validate before production use).
Recovery options
Neither option below is a bd command or a supported repair, and neither can guarantee that every value survives. Choose with the people who own the data, and run every step on a preserved copy.Restore from readable history
The reported procedure uses stock Dolt history. On the copy, find an earlier commit at which the candidate tables read cleanly. Readability needs a full-value read of each table, for exampleSELECT * FROM events AS OF '<commit>', and the same for
every other candidate table: a COUNT(*) can succeed without decoding a
single stored value, so it proves nothing here. Then restore an appropriate
table root from that version and reconcile it against current data.
History holds only versioned tables, so this route cannot restore a
clone-local table: not the wisp tables, and not events rows written after
migration 0062. If the unreadable value is in one of those, this route does
not apply.
History restores an older version, so account for:
- Deleted rows: rows deleted since that version come back unless you remove them again.
- Rows created since: rows created after that version are missing from the restored table and must be carried over from current data, where they may be the unreadable ones.
- Schema differences: the older version may predate columns or tables that later migrations added, so the restored table may not match the schema the migration cursor expects.
Dolt schema repair tool (experimental)
dolthub/dolt PR 11133 proposed an experimental schema repair tool. As of 2026-11-08 it is closed and unmerged, titled DO NOT MERGE, on branchzachmu/schema-repair-tool. Treat it
as a historical experimental route, not a released or supported tool, and do
not infer from its state whether a replacement exists. Verify current upstream
guidance with the Dolt maintainers before running any version of it.
Reports from its use are useful context, not a guarantee:
validation of a repaired copy
and the limits of sample-based checks.
Validate before production use
Validate the recovered copy before it replaces anything:- Full reads: read every row and every column of every relevant table,
not a sample: every candidate table of the stopped migration, and at least
issues,dependencies,labels,events,comments,wispsand everywisp_*table, with full-value queries such asSELECT * FROM eventson the copy. bd commands such asbd listorbd exportdo not read every row of every table, so they are not this check. Any read error, including either drift symptom, means the copy is not recovered. - Semantics: separately, check issue and dependency semantics against
what you expect, with bd pointed at the copy (
BEADS_DIRset to the copy’s.beads): issue counts by status, the dependency graph (bd blocked,bd ready), and the rows you reconciled by hand. Sampling alone is not a full validation. - Migration: rerun the migration on the copy with
bd migrate schemaand confirm it completes. On a remote-backed store, follow the designated migrator flow before publishing. - After migrating: run
bd recompute-blocked --json(see Repair blocked flags after migrating).
What this refusal does not cover
The refusal converts a returned error from a migration into this diagnosis. A raw engine panic is a different path: it does not reach bd as a returned error, so bd prints the panic instead of this refusal and does not intercept it. This release improves the diagnosis of returned errors and does not make every embedded panic path safe. If a command panics withinvalid hash length, the same preservation steps apply: stop, preserve a
full copy, and do not write to the store.