gastownhall/beads · error

finalizing dependencies.id for migration 0053: %w

Error message

finalizing dependencies.id for migration 0053: %w

What it means

Wraps failure of `ALTER TABLE dependencies MODIFY COLUMN id CHAR(36) NOT NULL`, the step that finalizes the id column type/nullability after backfill completes. The ALTER is what locks the column into its 0043/0053 shape before it becomes the primary key.

Source

Thrown at internal/storage/schema/migration_repairs.go:535

	}
	if remainingNull > 0 {
		// Fail with an actionable count now rather than let a subsequent
		// MODIFY COLUMN ... NOT NULL below abort with a generic "column
		// cannot be null" error, or silently key the table while leaving
		// NULL-id rows behind it.
		return fmt.Errorf("migration 0053: %d dependencies row(s) have no depends_on_issue_id/depends_on_wisp_id/depends_on_external target and cannot be assigned an id (ck_dep_one_target should prevent this); repair manually before retrying", remainingNull)
	}

	idIsPrimaryKey, err := schemaColumnInPrimaryKey(ctx, db, "dependencies", "id")
	if err != nil {
		return fmt.Errorf("checking dependencies.id primary key: %w", err)
	}
	if idIsPrimaryKey {
		return nil
	}

	if _, err := db.ExecContext(ctx, "ALTER TABLE dependencies MODIFY COLUMN id CHAR(36) NOT NULL"); err != nil {
		return fmt.Errorf("finalizing dependencies.id for migration 0053: %w", err)
	}

	hasAnyPrimaryKey, err := schemaHasPrimaryKey(ctx, db, "dependencies")
	if err != nil {
		return fmt.Errorf("checking dependencies for an existing primary key: %w", err)
	}
	if hasAnyPrimaryKey {
		// The #4690 drifted shape has dependencies keyed some other way (or
		// keyless): a table can carry only one PRIMARY KEY, so whatever is
		// there must go before id can become it. The uk_dep_* natural-identity
		// unique keys (0043) enforce the real uniqueness independently of
		// whatever this was, so dropping it is safe.
		if _, err := db.ExecContext(ctx, "ALTER TABLE dependencies DROP PRIMARY KEY"); err != nil {
			return fmt.Errorf("dropping dependencies' existing primary key for migration 0053: %w", err)
		}
	}
	if _, err := db.ExecContext(ctx, "ALTER TABLE dependencies ADD PRIMARY KEY (id)"); err != nil {
		return fmt.Errorf("keying dependencies.id for migration 0053: %w", err)

View on GitHub (pinned to 71377f2769)

Solutions

1. Ensure no other bd/Dolt process is using the database, then rerun — the repair is idempotent and re-checks state each time
2. Free disk space; ALTER TABLE rebuilds the table and needs headroom
3. For very large tables, run the migration in a maintenance window and disable process supervisors that kill long-running bd
4. Check the wrapped %w error for the precise server-side reason and act on it

Example fix

// before: ALTER killed by systemd timeout
sudo systemctl stop beads-timer  # or stop the scheduler restarting bd
bd ready                        // completes migration
// after: restart services
sudo systemctl start beads-timer

df -h /path/to/db   # ensure headroom for table rebuild
bd dolt sql -q 'SELECT COUNT(*) FROM dependencies' || echo 'db busy/unreachable'

if err := ensureSchema(ctx, db); err != nil {
    if strings.Contains(err.Error(), "finalizing dependencies.id for migration 0053") {
        // verify state, then resume — repair is idempotent
        return retryWithBackoff(ensureSchema)
    }
    return err
}

When it happens

Trigger: Backfill succeeded but the MODIFY COLUMN fails: duplicate NULLs were missed (blocked earlier), table locked by another writer, insufficient disk for the table rebuild, Dolt transaction conflict, or connection dropped during the (potentially long) ALTER on a large dependencies table.

Common situations: Large databases where ALTER takes minutes and a health-checker restarts bd mid-ALTER; concurrent bd process holding metadata locks; low-disk environments failing the table rebuild.

Related errors

• adding issues.%s for migration 0053: %w
• failed to scan peer for migration: %w
• failed to iterate peers for migration: %w
• failed to update encrypted password for peer %s: %w
• re-key id %s -> %s: %w

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