{"record":{"id":"4d084b8860d66214","repo":"hasura/graphql-engine","slug":"cannot-create-migrate-instance-w-4d084b","errorCode":null,"errorMessage":"cannot create migrate instance: %w","messagePattern":"cannot create migrate instance: %w","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"cli/migrate/util.go","lineNumber":187,"sourceCode":"\t\t\tSettingsStateStore:   cli.GetSettingsStateStore(ec, sourceName),\n\t\t},\n\t}\n\n\topts.hasuraOpts.PGDumpClient = ec.APIClient.PGDump\n\tif ec.HasMetadataV3 {\n\t\topts.hasuraOpts.PGSourceOps = ec.APIClient.V2Query\n\t\topts.hasuraOpts.MSSQLSourceOps = ec.APIClient.V2Query\n\t\topts.hasuraOpts.CitusSourceOps = ec.APIClient.V2Query\n\t\topts.hasuraOpts.BigQuerySourceOps = ec.APIClient.V2Query\n\t\topts.hasuraOpts.GenericQueryRequest = ec.APIClient.V2Query.Send\n\t} else {\n\t\topts.hasuraOpts.PGSourceOps = ec.APIClient.V1Query\n\t\topts.hasuraOpts.GenericQueryRequest = ec.APIClient.V1Query.Send\n\t}\n\n\tt, err := New(opts)\n\tif err != nil {\n\t\treturn nil, errors.E(op, fmt.Errorf(\"cannot create migrate instance: %w\", err))\n\t}\n\n\tif ec.Config.Version >= cli.V2 {\n\t\tt.databaseDrv.EnableCheckMetadataConsistency(true)\n\t}\n\n\tif ok, err := copyStateToCatalogStateAPIIfRequired(ec, sourceName); err != nil {\n\t\tec.Logger.Warn(err)\n\t} else if ok {\n\t\terr := t.ReScan()\n\t\tif err != nil {\n\t\t\treturn nil, errors.E(op, err)\n\t\t}\n\t}\n\n\treturn t, nil\n}\n","sourceCodeStart":169,"sourceCodeEnd":205,"githubUrl":"https://github.com/hasura/graphql-engine/blob/724551b9ae87845594ef0408cff0e50eb6c90dc5/cli/migrate/util.go#L169-L205","documentation":"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.","triggerScenarios":"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.","commonSituations":"`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).","solutions":["Read the wrapped error (%w) — it carries the actual cause; fix that first","Verify the server endpoint and admin secret in config.yaml and that the Hasura server is reachable (curl the /healthz endpoint)","Confirm the source kind supports migrations (PG, Citus, Cockroach, MSSQL, BigQuery)","Check the migrations/ directory URL (file scheme) exists and is readable"],"exampleFix":"# before\nendpoint: http://wrong-host:8080   # cannot create migrate instance: ... connection refused\n\n# after\nendpoint: http://localhost:8080    # correct, running server","handlingStrategy":"try-catch","validationCode":"// Fail fast on connectivity/config before building Migrate\nif err := ec.Validate(); err != nil { return err }\nif _, err := http.Get(cfg.Endpoint + \"/healthz\"); err != nil {\n    return fmt.Errorf(\"server unreachable: %w\", err)\n}","typeGuard":null,"tryCatchPattern":"m, err := migrate.NewMigrate(ec, false, \"\", hasura.SourceKindPG)\nif err != nil {\n    // err wraps the real cause; log it fully and surface to user\n    return errors.E(op, fmt.Errorf(\"cannot create migrate instance: %w\", err))\n}","preventionTips":["Health-check the server before migrate commands","Validate config.yaml endpoint/admin secret in CI","Restrict projects to migrations-supported source kinds"],"tags":["migrations","configuration","connection","hasura"],"backgroundTag":"migrate-init-failed","analyzedSha":"724551b9ae87845594ef0408cff0e50eb6c90dc5","analyzedAt":"2026-08-28T07:32:55.105Z","schemaVersion":2},"datasetVersion":"2026-08-28T11:17:15.048Z"}