RFC: Add Schema Coordinate to GraphQL Errors

[PascalSenn]

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

[netlify]

✅ Deploy Preview for graphql-spec-draft ready!

Name	Link
🔨 Latest commit	04e2431
🔍 Latest deploy log	https://app.netlify.com/projects/graphql-spec-draft/deploys/6900a65b5fcd5b0008dafddb
😎 Deploy Preview	https://deploy-preview-1200--graphql-spec-draft.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

---

To edit notification comments on pull requests, go to your Netlify project configuration.

[n1ru4l]

This would really help us simplify error tracking!

[ardatan]

Adding the schema coordinate together with the existing path expose the schema information. Now the user knows that hero's heroFriends is [Human], and it has name in it. An attacker can predict a lot of information about the schema unsafely by using required argument errors etc too.
If you say most clients request __typename anyway, but this is a request which is evaluated by the server, and the resolution of __typename is not the same with exposing the schema coordinate in every error.
If we already have __typename + path, we can always find the schema coordinate anyways. So why would we need an extra schema coordinate property in the errors?

[EmrysMyrddin]

After trying to actually implement walking the path to determine schema coordinate, it appears that the coordinate can be impossible to determine with certitude.

If there is a Union or an Interface involved in the path, you will need to visit the result to know the actual type.

But, in combination with non-nullable field, you have situations where can't determine the actual coordinate.

Example:

#schema.gql

interface Node {
  id: String!,
}

type Query {
  node(id: String!): Node!
}

type User implements Node {
  id: String!,
}

type Comment implements Node {
  id: String!,
}

#query.gql

query {
  node(id: 'a-user-id') {
    id
    __typename
  }
}

If an error occurs in the id resolver, you will get this result:

{ 
  data: null,
  errors: [{
    message: 'An error occured',
    path: ['node', 'id']
  }]
}

Now you have no way to determine if the coordinate is actually User.id or Comment.id.
The same applies for Unions.

[ardatan]

@EmrysMyrddin You're right but the security concern is still there, and if this schema coordinate property will be standard in the error object, then we should document this concern clearly.

[martinbonnin]

in combination with non-nullable field, you have situations where can't determine the actual coordinate.

@EmrysMyrddin this is yet another use case for onError: NULL and disabling error propagation. At this point error propagation has a bunch of issues (see also https://github.com/graphql/nullability-wg/) so I would rather optimise for the new onError: NULL case.