gastownhall/beads · error

staging migrations: %w

Error message

staging migrations: %w

What it means

Once the migration pass is verified, MigrateUp calls stageSchemaTables to stage the migrated schema tables in the Dolt working set so they can be committed. This error wraps a failure of that staging step — the schema changes are applied but could not be staged for the subsequent DOLT_COMMIT, leaving them uncommitted in the working set. The pass aborts without committing.

Source

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

	}
	if err := unstageIgnoredTables(ctx, db); err != nil {
		return applied, fmt.Errorf("unstaging ignored migration tables: %w", err)
	}

	if applied == 0 && !backfilled && appliedIgnored == 0 && !mainColumnAdded && !ignoredColumnAdded {
		return applied, nil
	}
	changedDirtyTables, err := changedDirtyTableSignatures(ctx, db, dirtyBeforeSignatures)
	if err != nil {
		return applied, fmt.Errorf("checking pre-existing dirty table diffs: %w", err)
	}
	if len(changedDirtyTables) > 0 {
		return applied, fmt.Errorf("pre-existing dirty tables changed during schema migration: %s", strings.Join(changedDirtyTables, ", "))
	}

	staged, err := stageSchemaTables(ctx, db, dirtyBefore)
	if err != nil {
		return applied, fmt.Errorf("staging migrations: %w", err)
	}
	if !staged {
		return applied, nil
	}
	if err := DrainCall(ctx, db, "CALL DOLT_COMMIT('-m', 'schema: apply migrations')"); err != nil {
		if !strings.Contains(strings.ToLower(err.Error()), "nothing to commit") {
			return applied, fmt.Errorf("committing migrations: %w", err)
		}
	}

	return applied, nil
}

func migrationWorkNeeded(ctx context.Context, db DBConn) (bool, error) {
	if !mainSource.atLatest(ctx, db) || !ignoredSource.atLatest(ctx, db) {
		return true, nil
	}
	// A database already at the latest numbered migration still needs work if it

View on GitHub (pinned to 71377f2769)

Solutions

1. Check the wrapped cause (%w) for the exact SQL error from stageSchemaTables and fix it (permissions, conflict, connection)
2. Inspect the Dolt working set (dolt status) for conflicts or corruption; resolve or reset it, then re-run MigrateUp
3. Ensure no other session is writing to the working set during migration (use MigrateUpWithLock and stop competing writers)
4. Verify the DB user can perform the staging DDL/DML on the schema tables
5. Re-run MigrateUp once staging can succeed so the schema changes get committed

Example fix

// before: read-only-ish user cannot stage migrated tables
GRANT SELECT, INSERT, UPDATE ON *.* TO 'bd'@'%';
// after: grant the DDL/staging privileges migrations need
GRANT ALL PRIVILEGES ON *.* TO 'bd'@'%';

// Pre-flight: session can write to the working set and it is conflict-free
rows, err := db.QueryContext(ctx, "SELECT conflict FROM dolt_status")
if err != nil {
    return fmt.Errorf("working set not writable: %w", err)
}
defer rows.Close()
for rows.Next() {
    var conflict bool
    if err := rows.Scan(&conflict); err == nil && conflict {
        return errors.New("working set has conflicts; resolve before migrating")
    }
}

applied, err := schema.MigrateUpWithLock(ctx, db)
if err != nil {
    if strings.Contains(err.Error(), "staging migrations:") {
        cause := errors.Unwrap(err)
        // Schema applied but not staged/committed; safe to retry after fix
        return fmt.Errorf("schema staged failed (%v); resolve and re-run MigrateUp", cause)
    }
    return err
}

When it happens

Trigger: Calling MigrateUp/MigrateUpWithLock when stageSchemaTables(ctx, db, dirtyBefore) errors — SQL failures issuing the staging statements (dolt add equivalents), permission failures, connection drops, or working-set conflicts while staging the migrated tables.

Common situations: Database user lacking privileges to stage/alter the working set, a corrupted or conflicted Dolt working set from a prior crash, concurrent sessions mutating the working set during staging, or connection instability on large schema changes.

Related errors

• dolt add %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/5cf8f6cd64411f54. Report an issue: GitHub.