Top GraphQL Errors and How to Fix them

07 May, 2021 | 3 min read
Top GraphQL Errors and How to Fix them
Top GraphQL Errors and How to Fix them

Error handling in GraphQL is different on both server and client side tooling. You no longer are looking at HTTP status codes to debug what went wrong for the request made. This makes one more involved in debugging errors, but thankfully there's a structure to the errors in GraphQL and we will look into it to see how to debug and fix them.

Let's take a typical GraphQL query:

query {
  author {
    id
    name
  }
}

The response of the above query can have the following objects:

  • data
  • errors or
  • both.
{
  "data": [{ id: 1, name: "Praveen"}],
  "errors": []
}
Top Level Errors Object in GraphQL Responses

When the response contains the errors object along with the data object, it could mean a partially correct response for the request. Digging into the errors object will give a better idea into what part of the query went wrong.

Identifying error types will help quickly fix them. Clients can encounter these types of errors while communicating with the GraphQL server.

Server Problems / Network errors

All the errors above come under the category of GraphQL errors with a response status code of 200. When there is a network error while trying to contact a GraphQL server, due to either the server being down or timeouts etc, then the response will be a status code of 4xx or 5xx.

If the server responds anything other than 200, the response is not successful due to either being a:

  • Bad request (400)
  • Unauthorized (401)
  • Gateway errors (5xx)

These are non-ideal scenarios where the original response couldn't be delivered via 200 (despite there is a possibility of a request containing an error). This non-standard response needs to be checked with the server for underlying issue like network errors etc.

Client side problems - Validation rules of GraphQL Query

GraphQL is strongly typed and it performs validation of all queries before executing them. It can reject a query if it is invalid based on a set of rules.

The validation rules could again be split into

  • malformed query
  • syntax or schema logic
  • variables and fragments not defined properly.

For example:

{
  "errors": [
    {
      "extensions": {
        "path": "$.variableValues",
        "code": "validation-failed"
      },
      "message": "unexpected variables in variableValues: products"
    }
  ]
}
unexpected variables in variableValues: id
unexpected variables in variableValues: id

This is a typical error that you get when a client makes a request with a variable that has not been defined. A common nightmare when using GUI tools like GraphiQL where the variables UI has remnants of variable usage from previous queries.

Read the source code for validation rules in graphql-js server to understand various query validation that goes through before executing the query.

Do note that validation errors never return any data to the client, the execution errors have the ability to return partial data sets. The operation could have been largely fulfilled but due to slow performance of a specific field or specific part of the query, it could result in partial data set.

Top-level errors

The default errors JSON includes message, locations and path. According to the working draft of the spec, it is also possible to send custom data in the extensions key.

Field level errors

{
 “errors”: [{
    “extensions”: {
    “path”: “$.selectionSet.dogs.selectionSet.name”,
    “code”: “validation-failed”
   },
   “message”: “field \”name\” not found in type: ‘dogs’”
 }]
}

In the above response, you can see the extensions key inside errors object that contains more metadata on what went wrong. Technically this error came out of using a field which doesn't exist (either due to Auth or schema not really having the field).

GraphQL Subscription Errors

Another common set of errors typically encountered while connecting with GraphQL servers comes when connecting to websocket connections for realtime subscriptions:

  • websocket connection could not be initalised. This needs a check with the URL of the websocket connection; note that websocket URLs start with ws or wss and not https.
  • invalid http upgrade (this could happen when http(s) is used for a websocket connection and the right connection split is not configured for ws)
  • connectionParams not passed for authorization headers. If you are using a JWT token, it needs to be passed via connectionParams using the GraphQL Client.

Resources

Close

Get Started with GraphQL Now

Hasura Cloud gives you a fully managed, production ready GraphQL API as a service to help you build modern apps faster.

HasuraCon, Our user conference is back!

We’re bringing together users from all over the world for a 2 day celebration of all things Hasura!
Discover the amazing products developers are building with Hasura. Level up your Hasura skills with live, in-depth workshops. Hear about all the big features and updates we are making to the Hasura GraphQL Engine and Hasura Cloud. Join us on 23rd & 24th June 2021!

Praveen Durairaju

Praveen Durairaju

Application Engineer. Tech Enthusiast. Follow on Twitter - https://twitter.com/@praveenweb

Read More

hand
Ready to get started?
Start for free on Hasura Cloud or you could contact our sales team for a detailed walk-through on how Hasura may benefit your business.
Stay in the know
Sign up for full access to our community highlights, new features, and occasional baby animal gifs! Oh, and we have a strict no-spam rule. ✌️