GraphQL RFC Tracker

RFC 0 / Strawman

Add Schema Coordinate to GraphQL Errors

Opened on2025-10-28
Updated on2025-11-14

At a glance

Spec PR description

Add an optional coordinate field to GraphQL errors that contains the schema coordinate of the object field or field argument associated with the error, enabling direct identification of schema elements that caused runtime errors.

📜 Problem Statement

When a GraphQL error occurs, developers must perform multiple steps to identify which type system member caused the error:

  1. Parse the schema
  2. Parse the operation
  3. Traverse the operation based on the path field in the error

This process is cumbersome and requires tooling to correlate runtime errors back to their schema definitions. While the path field identifies where in the response the error occurred, it doesn't directly indicate which schema element is responsible for the error.

Example

Consider this error response:

{
  "errors": [
    {
      "message": "Name for character with ID 1002 could not be fetched.",
      "locations": [{ "line": 6, "column": 7 }],
      "path": ["hero", "heroFriends", 1, "name"]
    }
  ]
}

To determine that this error originated from the Human.name field in the schema, developers must:

  • Load and parse the schema
  • Parse the GraphQL operation
  • Walk through the operation following the path ["hero", "heroFriends", 1, "name"]
  • Determine the types at each step to identify that heroFriends returns [Friend]
  • Conclude that the error is associated with Human.name

💡 Proposed Solution

Add an optional coordinate field to GraphQL errors that directly references the object fiel or field argument where the error originated.

Example

{
  "errors": [
    {
      "message": "Name for character with ID 1002 could not be fetched.",
      "locations": [{ "line": 6, "column": 7 }],
      "path": ["hero", "heroFriends", 1, "name"],
      "coordinate": "Human.name"
    }
  ]
}

In this example coordinate directly identifies Human.name in the schema as the source, without requiring any parsing or traversal

  1. Simplified Error Tracking: Developers can immediately identify which schema element caused an error without complex analysis.

  2. Better Tooling Support: IDEs, monitoring systems, and debugging tools can directly link errors to schema definitions.

The coordinate field should be included when:

  • An error originates from resolving a specific object field -> object field coordinate
  • An error originates from resolving a specific field argument -> field argument coordinate
  • An error originates from coercing a value of a input object -> field argument of the field that the input object is passed to

The coordinate field may be omitted when:

  • The error is not associated with a specific schema element
  • The server implementation cannot determine the appropriate coordinate

Timeline

  • Spec PR created on 2025-10-28 by PascalSenn
  • Commit pushed on 2025-10-28 by PascalSenn: RFC: Adds "coordinate" to errors