hasura/graphql-engine · error

error creating migrate instance: %w

Error message

error creating migrate instance: %w

What it means

NewAPIServer (the console's API backend) starts by creating a Migrate instance via migrate.NewMigrate; any failure there is re-wrapped as 'error creating migrate instance'. The root cause is in the wrapped error — usually server connectivity, config validation, or an unsupported source kind.

Source

Thrown at cli/pkg/console/apiserver.go:87

					Code:    "internal_error",
					Message: errMessage{updateRequiredMessage}.Error(),
				}
				c.AbortWithStatusJSON(http.StatusInternalServerError, &r)

				return
			}
		}

		c.Next()
	}
}

func NewAPIServer(address string, port string, ec *cli.ExecutionContext) (*APIServer, error) {
	var op errors.Op = "console.NewAPIServer"

	migrate, err := migrate.NewMigrate(ec, false, "", hasura.SourceKindPG)
	if err != nil {
		return nil, errors.E(op, fmt.Errorf("error creating migrate instance: %w", err))
	}

	gin.SetMode(gin.ReleaseMode)

	router := gin.New()
	// Setup API Router
	// Switch to "release" mode in production.
	gin.SetMode(gin.ReleaseMode)
	// An Engine instance with the Logger and Recovery middleware already attached.
	router.Use(allowCors())
	router.Use(cliProjectUpdateCheck(ec))

	apiServer := &APIServer{Router: router, Migrate: migrate, Address: address, Port: port, EC: ec}
	apiServer.setRoutes(ec.MigrationDir, ec.Logger)

	return apiServer, nil
}

View on GitHub (pinned to 724551b9ae)

Solutions

1. Check the wrapped error for the real cause
2. Ensure the Hasura server is up: curl http://localhost:8080/healthz
3. Verify endpoint + admin secret in config.yaml / env
4. Confirm the default source kind is a migrations-supported kind (PG/Citus/Cockroach/MSSQL/BigQuery)

Example fix

# before
$ hasura console   # server not yet started -> error creating migrate instance

# after
$ docker compose up -d   # start hasura first
$ hasura console

if _, err := http.Get(ec.Config.ServerConfig.Endpoint + "/healthz"); err != nil {
    return fmt.Errorf("start Hasura server before console: %w", err)
}

api, err := console.NewAPIServer(addr, port, ec)
if err != nil {
    // wrapped error carries the migrate failure cause; fix config and retry
    return err
}

When it happens

Trigger: Running `hasura console` when the migrate instance can't be built: server URL wrong/unreachable, admin secret missing, config version issues, or the database source kind doesn't support migrations.

Common situations: `hasura console` against a server that isn't started yet; endpoint typo in config.yaml; admin secret env var not exported in the shell; using a source kind (e.g. a data-connectors source) unsupported by migrations.

Related errors

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

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