ent/ent · error

ent/migrate: %w

Error message

ent/migrate: %w

What it means

This error is returned by the generated Schema.Diff method when creating a new schema.Migrate fails (e.g. the configured driver does not support the diff/migration feature). The library wraps the underlying error with the 'ent/migrate: ' prefix so callers can identify migration-layer failures. It is produced by the migratediff.tmpl code-generation template for all SQL dialects.

Source

Thrown at entc/gen/template/dialect/sql/feature/migratediff.tmpl:26

{{ define "migrate/diff" }}
// Diff compares the state read from a database connection or migration directory with
// the state defined by the Ent schema. Changes will be written to new migration files.
func Diff(ctx context.Context, url string, opts ...schema.MigrateOption) error {
    return NamedDiff(ctx, url, "changes", opts...)
}

// NamedDiff compares the state read from a database connection or migration directory with
// the state defined by the Ent schema. Changes will be written to new named migration files.
func NamedDiff(ctx context.Context, url, name string, opts ...schema.MigrateOption) error {
    return schema.Diff(ctx, url, name, Tables, opts...)
}
// Diff creates a migration file containing the statements to resolve the diff
// between the Ent schema and the connected database.
func (s *Schema) Diff(ctx context.Context, opts ...schema.MigrateOption) error {
    migrate, err := schema.NewMigrate(s.drv, opts...)
    if err != nil {
        return fmt.Errorf("ent/migrate: %w", err)
    }
    return migrate.Diff(ctx, Tables...)
}

// NamedDiff creates a named migration file containing the statements to resolve the diff
// between the Ent schema and the connected database.
func (s *Schema) NamedDiff(ctx context.Context, name string, opts ...schema.MigrateOption) error {
    migrate, err := schema.NewMigrate(s.drv, opts...)
    if err != nil {
        return fmt.Errorf("ent/migrate: %w", err)
    }
    return migrate.NamedDiff(ctx, name, Tables...)
}
{{ end }}

View on GitHub (pinned to 69d5d4deb1)

Solutions

1. Inspect the wrapped error (errors.Unwrap / %v of the returned error) to find why schema.NewMigrate failed
2. Verify the dialect driver passed to the schema supports the migration/diff interface
3. Ensure the generated code and the ent dialect package versions match (regenerate with the same ent version)
4. Switch to the official dialect driver (e.g. sql dialect via atlas) if a custom driver is in use

Example fix

// before
cs, err := entsql.Open(dialect.MySQL, dsn)
err = client.Schema.Diff(ctx)
// after
// use a driver that supports diff, e.g. the official sql driver, and check the wrapped cause
if err != nil {
    log.Fatalf("migration diff failed: %v", err) // shows underlying NewMigrate cause
}

// Go: check driver capability before Diff
if _, ok := drv.(interface {
	BeginTx(context.Context, *sql.TxOptions) (dialect.Tx, error)
}); !ok {
	return fmt.Errorf("driver %T does not support migrations", drv)
}

func supportsMigrate(drv dialect.Driver) bool {
	_, ok := drv.(interface {
		BeginTx(context.Context, *sql.TxOptions) (dialect.Tx, error)
	})
	return ok
}

err := client.Schema.Diff(ctx)
if err != nil {
	var base error
	if errors.As(err, &base) { /* log unwrapped NewMigrate cause */ }
	return fmt.Errorf("migration diff failed: %w", err)
}

When it happens

Trigger: Calling Schema.Diff(ctx, opts...) (or VersionedMigration variants) where schema.NewMigrate fails, typically because the dialect driver lacks the migrate/diff capability.

Common situations: Using a custom or third-party driver that does not implement the migration interface; enabling Atlas-based versioned migrations with an incompatible driver; dialect misconfiguration in the generated ent client.

Related errors

• {{ $pkg }}: {{ $plural }} is not achievable when selecting m
• {{ $pkg }}: missing required field "{{ $.Name }}.{{ $f.Name
• {{ $pkg }}: missing required edge "{{ $.Name }}.{{ $e.Name }
• creating schema directory: %w
• creating generate.go file: %w

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