hasura/graphql-engine · error

%s: decoding graphql responnse data: %w

Error message

%s: decoding graphql responnse data: %w

What it means

GetIntrospectionSchema raises this error (note the 'responnse' typo in the source) when the introspection response's 'data' field is present but json.Unmarshal of that raw JSON into hasura.IntrospectionSchema fails. The server answered successfully, but the schema payload did not match the Go types the CLI expects — typically due to schema shape changes between GraphQL/Hasura versions or unexpected types in the schema.

Source

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

		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"

	req, err := c.NewRequest(http.MethodPost, c.path, body)
	if err != nil {
		return nil, errors.E(op, err)
	}

	resp, err := c.LockAndDo(context.Background(), req, responseBodyWriter)
	if err != nil {
		return nil, errors.E(op, err)

View on GitHub (pinned to 724551b9ae)

Solutions

1. Update the CLI to the latest release matching your server generation — schema decoding gaps are usually fixed in newer versions
2. If targeting a non-Hasura or federated gateway, introspect a plain Hasura endpoint instead
3. Verify the response is not truncated (re-run the introspection query with curl and pipe to jq to validate JSON)
4. Report the schema fragment that fails to decode to the CLI maintainers if versions already match

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(), "decoding graphql responnse data") {
    // schema shape mismatch: upgrade CLI or introspect a compatible endpoint
    return fmt.Errorf("introspection schema decode failed (version skew?): %w", err)
  }
  return err
}

// Confirm version compatibility before introspecting
// GET /v1/version on the server; if newer than the CLI's supported major, upgrade the CLI first

func isSchemaDecodeError(err error) bool {
  return err != nil && strings.Contains(err.Error(), "decoding graphql responnse data")
}

schema, err := c.GetIntrospectionSchema()
if err != nil {
  if isSchemaDecodeError(err) {
    // fall back to raw JSON data and decode leniently, or upgrade CLI
    return handleSchemaDecodeFallback(err)
  }
  return err
}

When it happens

Trigger: An introspection response whose data contains constructs the CLI's IntrospectionSchema struct cannot decode: unknown type kinds from newer GraphQL spec versions (e.g. new directive applications, appliedDirectives), non-string fields where strings are expected, or very large schemas that get truncated by intermediaries producing invalid JSON.

Common situations: CLI version older than the Hasura/GraphQL server emitting a newer introspection format, federated/gateway endpoints returning extended schemas, or proxies truncating large introspection payloads.

Related errors

• %s: decoding graphql response errors: %w
• %s: %d %s
• %s: %w
• unable to fetch introspection schema: %w
• error in fetching introspection schema: %w

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