{"record":{"id":"d28b17a9a6713892","repo":"hasura/graphql-engine","slug":"s-decoding-graphql-response-errors-w","errorCode":null,"errorMessage":"%s: decoding graphql response errors: %w","messagePattern":"(.+?): decoding graphql response errors: %w","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"cli/internal/hasura/v1graphql/v1graphql.go","lineNumber":65,"sourceCode":"\t}\n\n\tif err != nil {\n\t\treturn nil, errors.E(op, err)\n\t}\n\n\terr = json.NewDecoder(responseBody).Decode(&respBody)\n\tif err != nil {\n\t\treturn nil, errors.E(op, err)\n\t}\n\n\tif respBody.Errors != nil {\n\t\tvar b []byte\n\n\t\terr := respBody.Errors.UnmarshalJSON(b)\n\t\tif err != nil {\n\t\t\treturn nil, errors.E(\n\t\t\t\top,\n\t\t\t\tfmt.Errorf(\"%s: decoding graphql response errors: %w\", opName, err),\n\t\t\t)\n\t\t}\n\n\t\treturn nil, errors.E(op, fmt.Errorf(\"%s: %w\", opName, err))\n\t}\n\n\tvar schema hasura.IntrospectionSchema\n\tif respBody.Data != nil {\n\t\terr = json.Unmarshal(*respBody.Data, &schema)\n\t\tif err != nil {\n\t\t\treturn nil, errors.E(\n\t\t\t\top,\n\t\t\t\tfmt.Errorf(\"%s: decoding graphql responnse data: %w\", opName, err),\n\t\t\t)\n\t\t}\n\t}\n\n\treturn schema, nil","sourceCodeStart":47,"sourceCodeEnd":83,"githubUrl":"https://github.com/hasura/graphql-engine/blob/724551b9ae87845594ef0408cff0e50eb6c90dc5/cli/internal/hasura/v1graphql/v1graphql.go#L47-L83","documentation":"This error is raised inside GetIntrospectionSchema when the GraphQL response contains a non-empty 'errors' array but the CLI fails to unmarshal that errors payload (respBody.Errors.UnmarshalJSON) into structured GraphQL error objects. In other words, the server returned errors in a shape the client's error type does not understand, so even the error content is lost and only the decoding failure is reported. Unlike sibling errors, it is not tagged KindHasuraAPI but wrapped generically with the operation name.","triggerScenarios":"A v1/graphql response whose 'errors' field is not the expected array of {message, extensions} objects — e.g. a plain string, a nested object, null sub-fields, or a non-JSON body that still parsed as a GraphQL envelope — causing json.Unmarshal inside the custom Errors type to fail.","commonSituations":"Non-Hasura GraphQL gateways or proxies that emit non-standard error shapes, older/newer Hasura versions with changed error formats, or custom response middleware on the server altering the errors field before the CLI sees it.","solutions":["Capture the raw response body (run CLI with --debug or reproduce the introspection query with curl) to see the actual 'errors' structure","If a proxy/middleware rewrites GraphQL errors, bypass it or fix it to pass the standard errors array through","Update the CLI to a version whose error unmarshalling matches your server's response format","If the server is not standard Hasura v1graphql, point the introspection flow at a compatible endpoint"],"exampleFix":"// before\nschema, err := c.GetIntrospectionSchema()\nif err != nil { return err }\n\n// after\nschema, err := c.GetIntrospectionSchema()\nif err != nil {\n  if strings.Contains(err.Error(), \"decoding graphql response errors\") {\n    // non-standard errors payload: inspect raw body via --debug / curl\n    return fmt.Errorf(\"non-standard GraphQL error payload from server: %w\", err)\n  }\n  return err\n}","handlingStrategy":"type-guard","validationCode":"// Reproduce the introspection query with curl and validate the errors field shape:\n// curl -s -H \"X-Hasura-Admin-Secret: $SECRET\" -d '{\"query\":\"IntrospectionQuery\"}' ENDPOINT/v1/graphql | jq 'type, .errors|type'","typeGuard":"func isGraphqlErrorDecodeError(err error) bool {\n  return err != nil && strings.Contains(err.Error(), \"decoding graphql response errors\")\n}","tryCatchPattern":"schema, err := c.GetIntrospectionSchema()\nif err != nil {\n  if isGraphqlErrorDecodeError(err) {\n    // server sent a non-standard errors payload; capture raw body and inspect\n    return inspectRawResponse(err)\n  }\n  return err\n}","preventionTips":["Avoid proxies/middleware that mutate GraphQL error bodies","Pin CLI to a version tested against your server version","Capture raw bodies in --debug mode when integrating new gateways"],"tags":["hasura","graphql","json-decode","introspection","go"],"backgroundTag":"graphql-error-decode-failed","analyzedSha":"724551b9ae87845594ef0408cff0e50eb6c90dc5","analyzedAt":"2026-08-28T07:32:55.105Z","schemaVersion":2},"datasetVersion":"2026-08-28T11:17:15.048Z"}