Resources

GraphQL Errors

Error handling in GraphQL differs on both server and client-side tooling. 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 provides insights into what part of the query went wrong.

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.

Common GraphQL Errors

Server Problems / Network Errors

Server-side errors occur when the GraphQL server cannot process the request due to configuration, network, or runtime issues. These errors are indicated by HTTP status codes other than 200. Common examples include:

• Bad Request (400): This indicates invalid input. For example:

  {
    "errors": [
      {
        "message": "Syntax Error: Unexpected Name 'queryx'",
        "locations": [{ "line": 1, "column": 1 }]
      }
    ]
  }
• Unauthorized (401): This occurs when authentication is missing or invalid.

  {
    "errors": [
      {
        "message": "Unauthorized access. Please log in."
      }
    ]
  }
• Gateway Errors (5xx): These indicate server-side failures such as timeouts or misconfigurations.

  {
    "errors": [
      {
        "message": "Internal Server Error. Please try again later."
      }
    ]
  }

Client-Side Problems - Validation Rules of GraphQL Query

GraphQL performs validation of all queries before executing them. Validation errors typically arise due to:

1. Malformed Query:

   query {
     user(id: 123 {
       name
     }
   }
   • Error:

     {
       "errors": [
         {
           "message": "Syntax Error: Expected ')', found '{'",
           "locations": [{ "line": 2, "column": 17 }]
         }
       ]
     }

2. Schema Logic Errors: When a query references a non-existent field.

   query {
     user(id: 123) {
       age
     }
   }
   • Error:

     {
       "errors": [
         {
           "message": "Cannot query field 'age' on type 'User'.",
           "locations": [{ "line": 3, "column": 7 }]
         }
       ]
     }

3. Variables and Fragments Not Defined Properly:

   query GetUser($id: ID!) {
     user(id: $userId) {
       name
     }
   }
   • Error:

     {
       "errors": [
         {
           "message": "Variable '$userId' is not defined.",
           "locations": [{ "line": 1, "column": 22 }]
         }
       ]
     }

Top-Level Errors

Top-level errors appear in the errors object and provide details about issues encountered during execution. These include:

• message: A brief description of the error.
• locations: The location in the query where the error occurred.
• path: The path to the field that caused the error.
• Example:

  {
    "errors": [
      {
        "message": "Field 'email' not found on type 'User'.",
        "locations": [{ "line": 3, "column": 9 }],
        "path": ["user", "email"]
      }
    ]
  }

GraphQL Subscription Errors

Subscription errors are encountered during real-time operations over WebSocket connections. Common issues include:

1. WebSocket Initialization Failure:

   • Error:

     {
       "errors": [
         {
           "message": "WebSocket connection failed: Invalid WebSocket URL."
         }
       ]
     }
   • Solution: Ensure the URL starts with ws:// or wss://.

2. Invalid HTTP Upgrade:

   • Error:

     {
       "errors": [
         {
           "message": "Invalid HTTP Upgrade for WebSocket connection."
         }
       ]
     }
   • Solution: Check server configuration to properly handle WebSocket upgrades.

3. Missing Connection Parameters:

   • Example:

     const wsLink = new WebSocketLink({
       uri: 'wss://graphql.example.com/graphql',
       options: {
         reconnect: true,
         connectionParams: {
           headers: {
             Authorization: `Bearer ${token}`,
           },
         },
       },
     });
   • Error:

     {
       "errors": [
         {
           "message": "Authorization headers missing in connectionParams."
         }
       ]
     }