hasura/graphql-engine · error

error in fetching introspection schema: %w

Error message

error in fetching introspection schema: %w

What it means

Same introspection-fetch failure as in codegen, but raised by `hasura actions create --derive-from`: before creating an action derived from an existing GraphQL operation, the CLI must fetch the server's introspection schema via o.EC.APIClient.V1Graphql.GetIntrospectionSchema(), and that HTTP call failed.

Source

Thrown at cli/commands/actions_create.go:92

	name        string
	deriveFrom  string
	withCodegen bool
}

func (o *actionsCreateOptions) run() error {
	var (
		op          errors.Op = "commands.actionsCreateOptions.run"
		introSchema hasura.IntrospectionSchema
		err         error
	)

	if o.deriveFrom != "" {
		o.deriveFrom = 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("error in fetching introspection schema: %w", err))
		}

		o.EC.Spinner.Stop()
	}

	// create new action
	o.EC.Spin("Creating the action...")
	actionCfg := actions.New(o.EC, o.EC.MetadataDir)
	o.EC.Spinner.Stop()

	err = actionCfg.Create(o.name, introSchema, o.deriveFrom)
	if err != nil {
		return errors.E(op, fmt.Errorf("error in creating action: %w", err))
	}

	opts := &MetadataApplyOptions{
		EC: o.EC,
	}

View on GitHub (pinned to 724551b9ae)

Solutions

1. Verify the server is reachable: `curl <endpoint>/healthz`.
2. Pass the correct --endpoint and --admin-secret.
3. Fix network/proxy issues between CLI and server.
4. If you cannot enable introspection, create the action without --derive-from and write its type definitions manually.

curl -sf -H "X-Hasura-Admin-Secret: $SECRET" "$ENDPOINT/v1/graphql" -d '{"query":"{ __schema { queryType { name } } }"}'

Catch, distinguish auth (401/403) vs connectivity failures from the wrapped error, fix credentials or network, then retry the create.

When it happens

Trigger: Running `hasura actions create <name> --derive-from '<query>'` when the engine at --endpoint is unreachable, the admin secret is wrong, or the server returns an error for the introspection query.

Common situations: Expired/incorrect --admin-secret, wrong endpoint URL (http vs https, port), engine container not running, network/VPN blocking the server, or server version restricting introspection.

Related errors

• unable to fetch 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/833c7fe53cf8ea06. Report an issue: GitHub.