docs: add guide on graphql-http errors #2006
Open
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
|
@sarahxsanders is attempting to deploy a commit to the The GraphQL Foundation Team on Vercel. A member of the Team first needs to authorize it. |
benjie
requested changes
Jun 5, 2025
There was a problem hiding this comment.
This is really good general reference that should be applicable to any server implementing GraphQL-over-HTTP (not just the reference implementation).
One concern is it does not incorporate the application/graphql-response+json media type. Since the spec is currently a draft I wouldn't normally be too concerned, except we do link to the spec so we should recommend its recommendations.
| ### Common causes | ||
|
|
||
| - Sending a `PUT` or `DELETE` request instead of `POST` or `GET` | ||
| - Sending a `GET` request for a mutation |
There was a problem hiding this comment.
Suggested change
| - Sending a `GET` request for a mutation | |
| - Sending a `GET` request for a mutation, or to a server that only supports `POST` requests |
|
|
||
| ### What it means | ||
|
|
||
| The HTTP layer succeeded, but the GraphQL response contains errors. |
There was a problem hiding this comment.
Suggested change
| The HTTP layer succeeded, but the GraphQL response contains errors. | |
| The HTTP layer succeeded, but the GraphQL request produced errors. |
|
|
||
| ```json | ||
| { | ||
| "data": null, |
There was a problem hiding this comment.
A query that fails validation will never have a data property:
Suggested change
| "data": null, |
|
|
||
| - Querying a field that doesn't exist | ||
| - Passing incorrect arguments to a field | ||
| - Violating schema constraints, such as non-nullability |
There was a problem hiding this comment.
Suggested change
| - Violating schema constraints, such as non-nullability | |
| - Violating schema constraints, such as non-nullability | |
| - Runtime errors during execution |
|
|
||
| ### How to debug | ||
|
|
||
| Check the `errors` array in the response body. A typical response looks like: |
There was a problem hiding this comment.
Suggested change
| Check the `errors` array in the response body. A typical response looks like: | |
| Check the `errors` array in the response body. | |
| If the response includes a `data` property then your query document is likely valid and you most likely hit a runtime exception - perhaps something went wrong on the server, you supplied invalid data, you're not allowed to do that, or some other runtime exception occurred. | |
| If the response does not include a `data` property it's likely there was a mistake in your request - an invalid GraphQL document or bad values for variables. A typical validation error response looks like: |
| @@ -0,0 +1,134 @@ | |||
| # Common `graphql-http` Errors and How to Debug Them | |||
There was a problem hiding this comment.
Suggested change
| # Common `graphql-http` Errors and How to Debug Them | |
| # Common HTTP Errors and How to Debug Them |
Comment on lines
+7
to
+11
| This guide outlines common `graphql-http` errors, what they mean, and how to debug them | ||
| effectively. These examples assume you're using the | ||
| [GraphQL over HTTP specification](https://graphql.github.io/graphql-over-http/draft/) | ||
| and an implementation such as [`graphql-http`](https://github.com/graphql/graphql-http) or any | ||
| server that follows the spec. |
There was a problem hiding this comment.
Suggested change
| This guide outlines common `graphql-http` errors, what they mean, and how to debug them | |
| effectively. These examples assume you're using the | |
| [GraphQL over HTTP specification](https://graphql.github.io/graphql-over-http/draft/) | |
| and an implementation such as [`graphql-http`](https://github.com/graphql/graphql-http) or any | |
| server that follows the spec. | |
| This guide outlines common errors, what they mean, and how to debug them | |
| effectively. These examples relate to servers that implement the | |
| [GraphQL over HTTP specification](https://graphql.github.io/graphql-over-http/draft/). Different servers may produce different error messages and status codes in some circumstances, so this document should be treated as a general guide rather than a canonical reference. |
| type: "separator", | ||
| title: "GraphQL over HTTP", | ||
| }, | ||
| "debug-errors": "Common `graphql-http` Errors", |
There was a problem hiding this comment.
Suggested change
| "debug-errors": "Common `graphql-http` Errors", | |
| "debug-errors": "Common GraphQL over HTTP Errors", |
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Description
graphql-httperrors (just some common ones) and how to debug themFeel free to suggest additional common errors if there are any that might be important to highlight here!