hasura/graphql-engine · error · errors.Error

%s: %d %s

Error message

 %s: %d 
%s

What it means

GetIntrospectionSchema returns this error when the HTTP response to a GraphQL introspection query sent to the server's v1/graphql endpoint has a status code other than 200. The message embeds the operation name, status code, and the raw body (which may hold a proxy error page or Hasura error JSON). It is classified errors.KindHasuraAPI — the server or an intermediary rejected the request outright.

Source

Thrown at cli/internal/hasura/v1graphql/v1graphql.go:45

	var op errors.Op = "v1graphql.Client.GetIntrospectionSchema"

	opName := "getIntrospectionSchema "
	query := map[string]string{
		"query": "\n    query IntrospectionQuery {\n      __schema {\n        queryType { name }\n        mutationType { name }\n        subscriptionType { name }\n        types {\n          ...FullType\n        }\n        directives {\n          name\n          description\n          locations\n          args {\n            ...InputValue\n          }\n        }\n      }\n    }\n\n    fragment FullType on __Type {\n      kind\n      name\n      description\n      fields(includeDeprecated: true) {\n        name\n        description\n        args {\n          ...InputValue\n        }\n        type {\n          ...TypeRef\n        }\n        isDeprecated\n        deprecationReason\n      }\n      inputFields {\n        ...InputValue\n      }\n      interfaces {\n        ...TypeRef\n      }\n      enumValues(includeDeprecated: true) {\n        name\n        description\n        isDeprecated\n        deprecationReason\n      }\n      possibleTypes {\n        ...TypeRef\n      }\n    }\n\n    fragment InputValue on __InputValue {\n      name\n      description\n      type { ...TypeRef }\n      defaultValue\n    }\n\n    fragment TypeRef on __Type {\n      kind\n      name\n      ofType {\n        kind\n        name\n        ofType {\n          kind\n          name\n          ofType {\n            kind\n            name\n            ofType {\n              kind\n              name\n              ofType {\n                kind\n                name\n                ofType {\n                  kind\n                  name\n                  ofType {\n                    kind\n                    name\n                  }\n                }\n              }\n            }\n          }\n        }\n      }\n    }\n  ",
	}
	responseBody := new(bytes.Buffer)

	var respBody struct {
		Data   *json.RawMessage `json:"data"`
		Errors *json.RawMessage `json:"errors"`
	}

	response, err := c.send(query, responseBody)
	if response.StatusCode != http.StatusOK {
		return nil, errors.E(
			op,
			errors.KindHasuraAPI,
			fmt.Errorf(" %s: %d \n%s", opName, response.StatusCode, responseBody.String()),
		)
	}

	if err != nil {
		return nil, errors.E(op, err)
	}

	err = json.NewDecoder(responseBody).Decode(&respBody)
	if err != nil {
		return nil, errors.E(op, err)
	}

	if respBody.Errors != nil {
		var b []byte

		err := respBody.Errors.UnmarshalJSON(b)
		if err != nil {
			return nil, errors.E(

View on GitHub (pinned to 724551b9ae)

Solutions

  1. Confirm the configured endpoint is the server base URL and the client appends /v1/graphql correctly; fix the URL if a 404
  2. Supply the correct admin secret (env var or config) for 401/403 responses
  3. Re-enable introspection (HASURA_GRAPHQL_ENABLE_INTROSPECTION=true) or export metadata from a server where it is allowed
  4. Retry on transient 5xx after confirming server health via /healthz
  5. Inspect the embedded response body — proxy HTML error pages reveal infrastructure causes

Example fix

// before
schema, err := c.GetIntrospectionSchema()
if err != nil { return err }

// after
schema, err := c.GetIntrospectionSchema()
if err != nil {
  if strings.Contains(err.Error(), "introspection") && err != nil {
    return fmt.Errorf("introspection query rejected; check endpoint, admin secret, introspection flag: %w", err)
  }
  return err
}
Defensive patterns

Strategy: try-catch

Validate before calling

// Pre-flight the graphql endpoint
req, _ := http.NewRequest(http.MethodPost, endpoint+"/v1/graphql", strings.NewReader(`{"query":"{ __typename }"}`))
req.Header.Set("X-Hasura-Admin-Secret", adminSecret)
resp, err := http.DefaultClient.Do(req)
if err != nil || resp.StatusCode != http.StatusOK {
  return fmt.Errorf("graphql endpoint not ready: status %d, err %v", resp.StatusCode, err)
}

Type guard

func isIntrospectionHTTPError(err error) bool {
  return err != nil && strings.Contains(err.Error(), ": 40") || strings.Contains(err.Error(), ": 50")
}

Try / catch

schema, err := c.GetIntrospectionSchema()
if err != nil {
  if isHasuraAPIError(err) {
    // parse embedded 'opName: status\nbody' and branch on 404/401/403/5xx
    return diagnoseHTTP(err)
  }
  return err
}

Prevention

When it happens

Trigger: Calling GetIntrospectionSchema (used by metadata export/inconsistency flows) when the endpoint URL is wrong (404), the admin secret is missing/wrong (401/403), introspection is disabled via HASURA_GRAPHQL_ENABLE_INTROSPECTION=false, or a gateway in front of Hasura returns 502/503 while the server restarts.

Common situations: CLI configured with an endpoint that includes or omits /v1/graphql incorrectly, expired or mistyped admin secret, introspection disabled on locked-down production instances, or transient 5xx during server deploys.

Related errors

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