hasura/graphql-engine · error

cannot create migrate instance: %w

Error message

cannot create migrate instance: %w

What it means

NewMigrate wraps a failure of migrate.New — the constructor that resolves the source driver (file://migrations) and the database driver (hasuradb via the server URL). So this error is an umbrella: the root cause is in the wrapped error and can be an unknown scheme, an unreachable server, bad config, or metadata inconsistencies.

Source

Thrown at cli/migrate/util.go:187

			SettingsStateStore:   cli.GetSettingsStateStore(ec, sourceName),
		},
	}

	opts.hasuraOpts.PGDumpClient = ec.APIClient.PGDump
	if ec.HasMetadataV3 {
		opts.hasuraOpts.PGSourceOps = ec.APIClient.V2Query
		opts.hasuraOpts.MSSQLSourceOps = ec.APIClient.V2Query
		opts.hasuraOpts.CitusSourceOps = ec.APIClient.V2Query
		opts.hasuraOpts.BigQuerySourceOps = ec.APIClient.V2Query
		opts.hasuraOpts.GenericQueryRequest = ec.APIClient.V2Query.Send
	} else {
		opts.hasuraOpts.PGSourceOps = ec.APIClient.V1Query
		opts.hasuraOpts.GenericQueryRequest = ec.APIClient.V1Query.Send
	}

	t, err := New(opts)
	if err != nil {
		return nil, errors.E(op, fmt.Errorf("cannot create migrate instance: %w", err))
	}

	if ec.Config.Version >= cli.V2 {
		t.databaseDrv.EnableCheckMetadataConsistency(true)
	}

	if ok, err := copyStateToCatalogStateAPIIfRequired(ec, sourceName); err != nil {
		ec.Logger.Warn(err)
	} else if ok {
		err := t.ReScan()
		if err != nil {
			return nil, errors.E(op, err)
		}
	}

	return t, nil
}

View on GitHub (pinned to 724551b9ae)

Solutions

1. Read the wrapped error (%w) — it carries the actual cause; fix that first
2. Verify the server endpoint and admin secret in config.yaml and that the Hasura server is reachable (curl the /healthz endpoint)
3. Confirm the source kind supports migrations (PG, Citus, Cockroach, MSSQL, BigQuery)
4. Check the migrations/ directory URL (file scheme) exists and is readable

Example fix

# before
endpoint: http://wrong-host:8080   # cannot create migrate instance: ... connection refused

# after
endpoint: http://localhost:8080    # correct, running server

// Fail fast on connectivity/config before building Migrate
if err := ec.Validate(); err != nil { return err }
if _, err := http.Get(cfg.Endpoint + "/healthz"); err != nil {
    return fmt.Errorf("server unreachable: %w", err)
}

m, err := migrate.NewMigrate(ec, false, "", hasura.SourceKindPG)
if err != nil {
    // err wraps the real cause; log it fully and surface to user
    return errors.E(op, fmt.Errorf("cannot create migrate instance: %w", err))
}

When it happens

Trigger: Calling migrate.NewMigrate (as done by Exec, run, RunOnSource, MetadataAPI, MigrateAPI, console startup) with an invalid database URL, wrong source kind, server not running, or when New's internal validation (e.g. checking migrations table consistency) fails.

Common situations: `hasura migrate apply` / `hasura metadata export` / `hasura console` against a server URL that's wrong or down; config.yaml with a bad endpoint or auth admin secret; using an unsupported source kind for migrations (IsMigrationsSupported returns false).

Related errors

• error creating migrate instance: %w
• operation failed: %w
• cannot write migration directory: %w
• applying migrations on source: %s: %w
• operation failed: %w

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