hasura/graphql-engine · error

unable to fetch introspection schema: %w

Error message

unable to fetch introspection schema: %w

What it means

Thrown when `hasura actions codegen --derive-from` needs the GraphQL introspection schema to derive an action, and the call to the Hasura GraphQL engine's introspection endpoint (o.EC.APIClient.V1Graphql.GetIntrospectionSchema()) fails. This means the CLI could not reach or query the configured Hasura server.

Source

Thrown at cli/commands/actions_codegen.go:103

type actionsCodegenOptions struct {
	EC         *cli.ExecutionContext
	actions    []string
	deriveFrom string
}

func (o *actionsCodegenOptions) run() (err error) {
	var (
		op            errors.Op = "commands.actionsCodegenOptions.run"
		derivePayload types.DerivePayload
	)
	if o.deriveFrom != "" {
		derivePayload.Operation = strings.TrimSpace(o.deriveFrom)
		o.EC.Spin("Deriving a Hasura operation...")

		introSchema, err := o.EC.APIClient.V1Graphql.GetIntrospectionSchema()
		if err != nil {
			return errors.E(op, fmt.Errorf("unable to fetch introspection schema: %w", err))
		}

		derivePayload.IntrospectionSchema = introSchema

		o.EC.Spinner.Stop()
	}

	if o.EC.Config.ActionConfig.Codegen.Framework == "" {
		return errors.E(
			op,
			stderrors.New(`could not find codegen config. For adding codegen config, run:

  hasura actions use-codegen`),
		)
	}

	// if no actions are passed, perform codegen for all actions
	o.EC.Spin("Generating code...")

View on GitHub (pinned to 724551b9ae)

Solutions

1. Verify the engine is up: curl the /healthz endpoint of your --endpoint.
2. Re-run with the correct --endpoint and --admin-secret (or HASURA_GRAPHQL_ADMIN_SECRET env var).
3. Check CLI-to-server network reachability (DNS, VPN, proxy, TLS).
4. If introspection is disabled/restricted on the server, enable it or derive the action manually without --derive-from.
5. Check for version mismatch between CLI and server; align versions.

curl -sf "$ENDPOINT/healthz" && curl -sf -H "X-Hasura-Admin-Secret: $SECRET" "$ENDPOINT/v1/graphql" -d '{"query":"{ __typename }"}'

Catch the error, inspect the wrapped cause for HTTP status (401 => fix admin secret, connection refused => fix endpoint) and surface a targeted message.

When it happens

Trigger: Running actions codegen with --derive-from while the Hasura engine at --endpoint is down, unreachable, protected by an invalid --admin-secret, or returning a non-200/error response from /v1/graphql introspection.

Common situations: Wrong or missing --endpoint/--admin-secret flags, expired admin secret, server behind auth proxy rejecting the CLI, local docker engine not started, or Hasura version that errors on the introspection query the CLI sends.

Related errors

• error in fetching introspection schema: %w
• cannot export metadata from server: %w
• exporting metadata from server: %w
• pulling latest actions codegen files from internet failed: %
• setting up codegen-assets repo failed (this is required for

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