gastownhall/beads · error

backfill custom tables: %w

Error message

backfill custom tables: %w

What it means

This error wraps a failure in ensureBackfilledCustomStatusesCustomTypes, the post-migration backfill that populates custom status/type rows to their canonical values. Main schema migrations have already applied at this point (applied count is still returned), so the database may be partially through the pass when this fires.

Source

Thrown at internal/storage/schema/schema.go:662

		return 0, fmt.Errorf("reading pre-migration dirty table diffs: %w", err)
	}
	// Captured before the main migrations run: the aux re-key uses it to
	// distinguish the lineage's first rekey-aware migration (run the pass)
	// from a fresh clone of an already-converged lineage (record the marker
	// only, bd-578h9.4).
	mainVersionBefore, err := mainSource.currentVersion(ctx, db)
	if err != nil {
		return 0, fmt.Errorf("reading pre-migration schema version: %w", err)
	}

	applied, mainColumnAdded, err := mainSource.migrate(ctx, db, 0)
	if err != nil {
		return applied, err
	}

	backfilled, err := ensureBackfilledCustomStatusesCustomTypes(ctx, db)
	if err != nil {
		return applied, fmt.Errorf("backfill custom tables: %w", err)
	}

	// #4259: rewrite any per-clone-random dependency ids (minted by 0043's
	// DEFAULT (UUID()) before this fix) to the deterministic key, so independently
	// migrated clones converge to byte-identical, merge-safe dependencies. Runs
	// here, after the schema migrations (0050 has asserted the canonical schema),
	// and only on a pass where migration work was needed.
	rekeyed, err := rekeyDependencyIDs(ctx, db)
	if err != nil {
		return applied, fmt.Errorf("rekey dependency ids: %w", err)
	}
	backfilled = backfilled || rekeyed

	// bd-6dnrw.2: converge the events/comments/snapshots primary keys that
	// migration 0037 randomized per-clone, the same hazard class on the aux
	// tables. Gated on the clone-local ignored marker (recorded later in this
	// pass by ignoredSource.migrate) so it runs exactly once per clone instead
	// of churning synced rows on every later migration pass — and on the

View on GitHub (pinned to 71377f2769)

Solutions

1. Inspect the wrapped cause for the exact failing backfill statement/row
2. Fix or normalize the offending custom status/type rows, then re-run MigrateUp (passes are idempotent)
3. Ensure the database is opened read-write with no concurrent writers during the pass
4. If a previous pass crashed mid-backfill, re-running MigrateUp should resume/complete it; restore from a Dolt commit if state is inconsistent

Example fix

// before: ignoring the error and opening anyway
_, _ = schema.MigrateUp(ctx, db)
// after: fail fast and keep the applied count
applied, err := schema.MigrateUp(ctx, db)
if err != nil {
    return fmt.Errorf("open aborted after %d migrations: %w", applied, err)
}

// Sanity-check custom statuses/types tables exist and are writable before migrating
for _, t := range []string{"issue_statuses", "issue_types"} {
    if _, err := db.QueryContext(ctx, "SELECT 1 FROM "+t+" LIMIT 1"); err != nil {
        return fmt.Errorf("%s unreadable: %w", t, err)
    }
}

func isBackfillErr(err error) bool {
    return err != nil && strings.Contains(err.Error(), "backfill custom tables")
}

applied, err := schema.MigrateUp(ctx, db)
if isBackfillErr(err) {
    return fmt.Errorf("migration partially applied (%d); fix backfill cause and re-run: %w", applied, err)
}

When it happens

Trigger: Calling MigrateUp/MigrateUpWithLock on a database needing migration where the custom statuses/types backfill INSERT/UPDATE fails - constraint violations from unexpected row data, Dolt write errors, or a working set that cannot be staged/committed.

Common situations: Legacy databases with hand-edited issue types/statuses that violate backfill expectations; read-only or concurrently-written databases mid-pass; interrupted earlier passes leaving unexpected rows.

Related errors

• %s: %w
• failed to migrate credential keys: %w
• failed to update encrypted password for peer %s: %w
• failed to initialize schema: %w
• failed to rebuild pool after migration: %w

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