hasura/graphql-engine · error

%s: %w

Error message

%s: %w

What it means

This is the fallback wrap in GetIntrospectionSchema applied when the response contained GraphQL errors and unmarshalling them succeeded but produced an error value without further detail; the message is simply '<opName>: <err>'. It represents a server-reported GraphQL error (data-level failure with HTTP 200) rather than a transport or HTTP-status problem — the introspection query executed but the server responded with errors in the GraphQL envelope.

Source

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

	}

	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(
				op,
				fmt.Errorf("%s: decoding graphql response errors: %w", opName, err),
			)
		}

		return nil, errors.E(op, fmt.Errorf("%s: %w", opName, err))
	}

	var schema hasura.IntrospectionSchema
	if respBody.Data != nil {
		err = json.Unmarshal(*respBody.Data, &schema)
		if err != nil {
			return nil, errors.E(
				op,
				fmt.Errorf("%s: decoding graphql responnse data: %w", opName, err),
			)
		}
	}

	return schema, nil
}

func (c *Client) send(body any, responseBodyWriter io.Writer) (*httpc.Response, error) {
	var op errors.Op = "v1graphql.Client.send"

View on GitHub (pinned to 724551b9ae)

Solutions

1. Print the full wrapped error — the underlying GraphQL message usually names the exact cause (permission, validation, disabled introspection)
2. Retry with the correct admin secret / admin role credentials
3. Check and repair metadata consistency on the server (inconsistent objects often surface as GraphQL errors)
4. Match CLI and server major versions so the introspection query is supported

Example fix

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

// after
schema, err := c.GetIntrospectionSchema()
if err != nil {
  // HTTP was 200; the GraphQL envelope itself reported errors
  return fmt.Errorf("server returned GraphQL errors for introspection: %w", err)
}

// Run a trivial authenticated query first to confirm the role can read the schema
// POST /v1/graphql {"query":"{ __schema { queryType { name } } }"} must return data, not errors

func isGraphqlEnvelopeError(err error) bool {
  return err != nil && strings.Contains(err.Error(), "introspection:") && !strings.Contains(err.Error(), "decoding")
}

schema, err := c.GetIntrospectionSchema()
if err != nil {
  if isGraphqlEnvelopeError(err) {
    // HTTP 200 but GraphQL errors: the wrapped message names the cause
    return fmt.Errorf("graphql errors: %w", err)
  }
  return err
}

When it happens

Trigger: HTTP 200 responses whose body has a populated 'errors' array: e.g. introspection disabled or forbidden for the requesting role, 'validation failed' for malformed introspection queries, role lacking permission on the schema, or server-internal errors surfaced as GraphQL errors.

Common situations: Connecting with an admin secret that resolves to a restricted role, running introspection against servers where the schema is intentionally hidden, version skew producing unsupported introspection features, or corrupted metadata causing the GraphQL layer to error.

Related errors

• %s: %d %s
• %s: decoding graphql response errors: %w
• %s: decoding graphql responnse data: %w
• pg_dump request: %d %s
• bigquery_run_sql api request failed %d

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