hasura/graphql-engine · error

unable to initialize migrations driver: %w

Error message

unable to initialize migrations driver: %w

What it means

Returned by `hasura migrate squash` when migrate.NewMigrate fails to build the migrations driver for the selected source, combining project directory state and server state.

Source

Thrown at cli/commands/migrate_squash.go:114

	newVersion int64

	deleteSource bool
	Source       cli.Source
}

func (o *migrateSquashOptions) run() error {
	var op errors.Op = "commands.migrateSquashOptions.run"

	o.EC.Logger.Warnln(
		"This command is currently experimental and hence in preview, correctness of squashed migration is not guaranteed!",
	)

	o.EC.Spin(fmt.Sprintf("Squashing migrations from %d to latest...", o.from))
	defer o.EC.Spinner.Stop()

	migrateDrv, err := migrate.NewMigrate(o.EC, true, o.Source.Name, o.Source.Kind)
	if err != nil {
		return errors.E(op, fmt.Errorf("unable to initialize migrations driver: %w", err))
	}

	status, err := migrateDrv.GetStatus()
	if err != nil {
		return errors.E(op, fmt.Errorf("finding status: %w", err))
	}

	var toMigration, fromMigration *migrate.MigrationStatus

	fromMigration, ok := status.Read(o.from)
	if !ok {
		return errors.E(
			op,
			fmt.Errorf(
				"validating 'from' migration failed. Make sure migration with version %v exists",
				o.from,
			),
		)

View on GitHub (pinned to 724551b9ae)

Solutions

1. Verify the database name and endpoint config
2. Run `hasura migrate status` to confirm driver init works
3. Align CLI and server versions
4. Check admin secret env var

hasura migrate status --database-name <db> # confirms driver init works

When it happens

Trigger: Invalid or missing --database-name, unsupported source kind, or failure contacting the server while initializing the driver.

Common situations: config.yaml not pointing at the right database, wrong endpoint/admin secret, CLI version older than the server's metadata API.

Related errors

• error in creation of new migrate instance %w
• finding status: %w
• unable to move migrations from project for: %v : %w
• cannot create migration: %w
• database driver: unknown driver %v

AI-assisted analysis of hasura/graphql-engine@724551b9ae (2026-08-28). Data as JSON: /api/errors/aee324f39339afa7. Report an issue: GitHub.