gastownhall/beads · error

committing migration step

Error message

committing migration step: %w

What it means

This error is returned when `CALL DOLT_COMMIT('-m', ?)` fails while committing a migration step (internal/storage/schema/schema.go:1753). The code deliberately tolerates a 'nothing to commit' result (an idempotent no-op migration) but any other commit error aborts the pass. It means the migration's changes and cursor row are staged but not durably committed to Dolt history.

Solutions

1. Read the wrapped inner error to identify the actual DOLT_COMMIT failure cause.
2. Check disk space and write permissions on the .beads directory; free space or fix the mount and retry.
3. Run `bd doctor` to detect and repair working-set/database corruption.
4. Ensure no concurrent `bd`/Dolt processes touch the database; kill stale processes and retry the migration pass.
5. If Dolt history/working set is corrupted, restore the .beads database from backup and re-run migrations.

Example fix

// before: commit fails silently blocked by full disk
# committing migration step: write .dolt/noms: no space left on device
// after: free space (or relocate the data dir), verify, retry
df -h .beads
bd doctor
bd migrate up

// Check storage headroom and writability before a committing migration pass
if info, err := os.Statfs(".beads"); err == nil && info.Bavail*uint64(info.Bsize) < minFreeBytes {
    return fmt.Errorf("insufficient disk space for migration commits")
}
if f, err := os.Create(".beads/.write-test"); err != nil {
    return fmt.Errorf(".beads not writable: %w", err)
} else { f.Close(); os.Remove(".beads/.write-test") }

if err := runMigrations(ctx, db, src, min, 0, true); err != nil {
    if strings.Contains(err.Error(), "committing migration step: ") &&
       !strings.Contains(strings.ToLower(err.Error()), "nothing to commit") {
        // real DOLT_COMMIT failure: free disk / repair via bd doctor,
        // then retry — per-step design makes retries converge
        if fixErr := repairAndVerify(ctx); fixErr != nil { return fixErr }
        return runMigrations(ctx, db, src, min, 0, true)
    }
    return err
}

When it happens

Trigger: DOLT_COMMIT fails during commitMigrationStep with an error other than 'nothing to commit': Dolt merge/working-set conflicts, an author identity or commit environment problem, storage write failure (disk full, permissions), or internal Dolt state errors on the embedded path.

Common situations: Disk full while Dolt writes the commit; corrupted working set after a crash; .beads directory permissions changed (read-only mount); concurrent access corrupting the working set; an old/incompatible embedded Dolt engine version rejecting the commit.

Related errors

• committing migration
• committing migrations
• backfill custom tables
• checking dirty tables against pending ignored migrations
• checking dirty tables against pending migrations

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

Appendix: source

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

	for table := range dirtyAfter {
		if _, wasDirty := dirtyBeforeStep[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 fmt.Errorf("dolt add %s: %w", table, err)
		}
	}
	if err := DrainCall(ctx, db, "CALL DOLT_COMMIT('-m', ?)", "schema: apply migration "+migrationName); err != nil {
		if !strings.Contains(strings.ToLower(err.Error()), "nothing to commit") {
			return fmt.Errorf("committing migration step: %w", err)
		}
	}
	return nil
}

View on GitHub (pinned to 71377f2769)