ent/ent · error

sql/schema: WithMigrationMode(ModeReplay) requires versioned

Error message

sql/schema: WithMigrationMode(ModeReplay) requires versioned migrations: WithDir()

What it means

Configuration-consistency guard in the Atlas setup: ModeReplay makes the migrator replay existing versioned files instead of computing diffs, which is only meaningful when a migration directory was supplied. The check fires when WithMigrationMode(ModeReplay) was combined with a nil a.dir (no WithDir), making replay impossible. The offending input is the mutually inconsistent option pair.

Source

Thrown at dialect/sql/schema/atlas.go:587

		a.diffHooks = append(a.diffHooks, withoutForeignKeys)
	}
	if a.dir != nil && a.fmt == nil {
		switch a.dir.(type) {
		case *sqltool.GooseDir:
			a.fmt = sqltool.GooseFormatter
		case *sqltool.DBMateDir:
			a.fmt = sqltool.DBMateFormatter
		case *sqltool.FlywayDir:
			a.fmt = sqltool.FlywayFormatter
		case *sqltool.LiquibaseDir:
			a.fmt = sqltool.LiquibaseFormatter
		default: // migrate.LocalDir, sqltool.GolangMigrateDir and custom ones
			a.fmt = sqltool.GolangMigrateFormatter
		}
	}
	// ModeReplay requires a migration directory.
	if a.mode == ModeReplay && a.dir == nil {
		return errors.New("sql/schema: WithMigrationMode(ModeReplay) requires versioned migrations: WithDir()")
	}
	return nil
}

// create is the Atlas engine based online migration.
func (a *Atlas) create(ctx context.Context, tables ...*Table) (err error) {
	if a.universalID {
		tables = append(tables, NewTypesTable())
	}
	if a.driver != nil {
		a.sqlDialect, err = a.entDialect(ctx, a.driver)
		if err != nil {
			return err
		}
	} else {
		c, err := sqlclient.OpenURL(ctx, a.url)
		if err != nil {
			return err

View on GitHub (pinned to 69d5d4deb1)

Solutions

1. Add WithDir(...) pointing at your versioned migration directory when using WithMigrationMode(ModeReplay).
2. Or drop ModeReplay and use the default (Modes of live diff/create) if you do not maintain versioned migrations.

When it happens

Trigger: Thrown at dialect/sql/schema/atlas.go:587 when the library encounters an invalid state.

Common situations: See trigger scenarios.

AI-assisted analysis of ent/ent@69d5d4deb1 (2026-09-03). Data as JSON: /api/errors/66b768617ffb67f2. Report an issue: GitHub.