gastownhall/beads · error

dolt add %s: %w

Error message

dolt add %s: %w

What it means

stageSchemaTables wraps a failure from the `CALL DOLT_ADD('-f', ?)` stored-procedure invocation that force-stages a table into the Dolt working set during migration. DOLT_ADD is Dolt's SQL equivalent of `dolt add`; if the procedure call itself errors (bad table name, session/catalog issues, procedure unavailable), the error is wrapped as `dolt add <table>: <cause>` so the failing table is identified.

Source

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

	if err != nil {
		return false, err
	}
	for table := range tablesAfter {
		if _, wasDirty := dirtyBefore[table]; wasDirty {
			continue
		}
		tableSet[table] = struct{}{}
	}

	tables := make([]string, 0, len(tableSet))
	for table := range tableSet {
		tables = append(tables, table)
	}
	sort.Strings(tables)

	for _, table := range tables {
		if err := DrainCall(ctx, db, "CALL DOLT_ADD('-f', ?)", table); err != nil {
			return false, fmt.Errorf("dolt add %s: %w", table, err)
		}
	}
	return len(tables) > 0, nil
}

func existingCommittableTables(ctx context.Context, db DBConn) (map[string]struct{}, error) {
	rows, err := db.QueryContext(ctx, `
		SELECT t.TABLE_NAME
		FROM INFORMATION_SCHEMA.TABLES t
		WHERE t.TABLE_SCHEMA = DATABASE()
		  AND t.TABLE_TYPE = 'BASE TABLE'
		  AND NOT EXISTS (
			SELECT 1 FROM dolt_ignore di
			WHERE di.ignored = 1
			  AND t.TABLE_NAME LIKE di.pattern
		  )
	`)
	if err != nil {

View on GitHub (pinned to 71377f2769)

Solutions

1. Inspect the wrapped cause: if the table no longer exists, re-run the migration — staging recomputes dirty tables at start and will skip it.
2. Verify the backend is Dolt and the dolt server version supports CALL DOLT_ADD with '-f'; upgrade the Dolt server if not.
3. Check the connection is healthy (no prior poisoned-catalog-snapshot statement in the session); open a fresh connection and retry MigrateUp.
4. If DOLT_ADD is unsupported in your environment, ensure the table is committed via an alternative path before MigrateUp completes.

Example fix

// before
if err := DrainCall(ctx, db, "CALL DOLT_ADD('-f', ?)", table); err != nil {
    return false, fmt.Errorf("dolt add %s: %w", table, err)
}
// after
if err := DrainCall(ctx, db, "CALL DOLT_ADD('-f', ?)", table); err != nil {
    if dberrors.IsTableNotExist(err) {
        continue // table vanished mid-migration; nothing to stage
    }
    return false, fmt.Errorf("dolt add %s: %w", table, err)
}

// before MigrateUp: ensure backend is Dolt and procedure exists
var one int
if err := db.QueryRowContext(ctx, "SELECT COUNT(*) FROM information_schema.routines WHERE routine_name = 'dolt_add'").Scan(&one); err != nil || one == 0 {
    return fmt.Errorf("DOLT_ADD procedure unavailable on this backend")
}

func isDoltProcMissing(err error) bool {
    var mysqlErr *mysql.MySQLError
    return errors.As(err, &mysqlErr) && (mysqlErr.Number == 1305 /* PROCEDURE does not exist */)
}

err := MigrateUp(ctx, db)
var doltErr error
if errors.As(err, &doltErr) && strings.Contains(err.Error(), "dolt add ") {
    log.Printf("staging failed for table; retrying migration: %v", err)
    err = MigrateUp(ctx, freshDB())
}

When it happens

Trigger: Called from MigrateUp after running migrations, or directly by TestStageSchemaTablesSkipsIgnoredTables. The CALL fails for a table that became newly-dirty or newly-committable (present in dolt_status or existingCommittableTables and not dirty before) — e.g. the table was dropped mid-migration, DOLT_ADD is unavailable/wrong-case on the server, or the connection session is in a bad state after a prior failed statement.

Common situations: A migration step creates then drops a temp table so it is dirty but gone by staging time; running against a non-Dolt MySQL backend where the DOLT_ADD procedure does not exist; Dolt version downgrades where the '-f' flag or procedure arity is unsupported; connection drops mid-migration.

Related errors

• staging migrations: %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/8fe4189b6f34b160. Report an issue: GitHub.