From ac2173310b12848625efdb5602e2b8ac0e011848 Mon Sep 17 00:00:00 2001 From: sarahxsanders Date: Fri, 30 May 2025 14:21:06 -0400 Subject: [PATCH 01/12] add guide on graphql-http errors --- src/pages/learn/_meta.ts | 1 + src/pages/learn/best-practices.mdx | 5 ++ src/pages/learn/debug-errors.mdx | 134 +++++++++++++++++++++++++++++ 3 files changed, 140 insertions(+) create mode 100644 src/pages/learn/debug-errors.mdx diff --git a/src/pages/learn/_meta.ts b/src/pages/learn/_meta.ts index ded3ef9830..cfd17050a7 100644 --- a/src/pages/learn/_meta.ts +++ b/src/pages/learn/_meta.ts @@ -27,4 +27,5 @@ export default { performance: "", security: "", federation: "", + "debug-errors": "Common `graphql-http` Errors", } diff --git a/src/pages/learn/best-practices.mdx b/src/pages/learn/best-practices.mdx index 5c9b5527d4..7cf153a6af 100644 --- a/src/pages/learn/best-practices.mdx +++ b/src/pages/learn/best-practices.mdx @@ -53,5 +53,10 @@ The articles in this section should not be taken as gospel, and in some cases ma link: "/learn/security/", description: "Protect GraphQL APIs from malicious operations", }, + { + title: "Common Errors", + link: "/learn/debug-errors/", + description: "Learn about common `graphql-http` errors and how to debug them.", + } ]} /> diff --git a/src/pages/learn/debug-errors.mdx b/src/pages/learn/debug-errors.mdx new file mode 100644 index 0000000000..97ecb3b740 --- /dev/null +++ b/src/pages/learn/debug-errors.mdx @@ -0,0 +1,134 @@ +# Common `graphql-http` Errors and How to Debug Them + +When building or consuming a GraphQL API over HTTP, it's common to run into +errors, especially during development. Understanding how to recognize and resolve these issues +can save you time and frustration. + +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. + +## `400 Bad Request`: Syntax or parse errors + +### What it means + +The server couldn't parse your request. Either the GraphQL query string is malformed, +or the JSON body isn't valid. + +### Common causes + +- JSON syntax errors +- Sending a plain string without wrapping it in `{ "query": "..." }` +- Using `Content-Type: application/graphql` without supporting it + +### How to debug + +- Validate your JSON body using a linter or formatter. +- Make sure you're sending a `POST` request with a `Content-Type: application/json` header. +- Verify that the GraphQL query is syntactically correct. Use an IDE or a linter to verify it. + +## `405 Method Not Allowed`: Wrong HTTP Method + +### What it means + +You're using an unsupported HTTP method. Most GraphQL servers require `POST` for mutations +and may allow `GET` for queries. + +### Common causes + +- Sending a `PUT` or `DELETE` request instead of `POST` or `GET` +- Sending a `GET` request for a mutation + +### How to debug + +- Check your HTTP method. Mutations must use `POST`. +- Make sure your server supports `GET` for queries. +- Refer to the [GraphQL over HTTP spec](https://graphql.github.io/graphql-over-http/draft/) to +confirm method support. + +## `415 Unsupported Media Type` + +### What it means + +The server doesn't understand the request's `Content-Type`. + +### Common causes + +- Sending a GraphQL query with `Content-Type: text/plain` or another unsupported type +- Omitting the `Content-Type` header in a `POST` request + +### How to debug + +- Set the header explicitly: `Content-Type: application/json`. +- If you're using `application/graphql`, verify your server supports it. This content type +is optional. + +## `422 Unprocessable Entity`: Missing or invalid `query` + +### What it means + +The server received the request, but the `query` field was missing or invalid. + +### Common causes + +- Sending `{}` with no `query` key +- Sending variables or an operation name without a query + +### How to debug + +Always include a `query` field in your request body. For example: + +```json +{ + "query": "{ user(id: 1) { name } }" +} +``` + +## `500 Internal Server Error`: Unexpected server failures + +### What it means + +Something went wrong on the server. + +### Common causes + +- An unhandled exception in a resolver +- Schema validation issues during server startup +- Missing or misconfigured middleware + +### How to debug + +- Check server logs or stack traces. +- Add error handling to resolvers. + +## GraphQL errors with `200 OK` + +### What it means + +The HTTP layer succeeded, but the GraphQL response contains errors. + +### Common causes + +- Querying a field that doesn't exist +- Passing incorrect arguments to a field +- Violating schema constraints, such as non-nullability + +### How to debug + +Check the `errors` array in the response body. A typical response looks like: + +```json +{ + "data": null, + "errors": [ + { + "message": "Cannot query field \"foo\" on type \"Query\".", + "locations": [{ "line": 1, "column": 3 }] + } + ] +} +``` + +Compare your query against the schema using introspection or an IDE. \ No newline at end of file From 79acc145d21791ecb0831465199f8f9b8574844e Mon Sep 17 00:00:00 2001 From: sarahxsanders Date: Fri, 30 May 2025 14:26:27 -0400 Subject: [PATCH 02/12] add new section for GraphQL over HTTP content --- src/pages/learn/_meta.ts | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/src/pages/learn/_meta.ts b/src/pages/learn/_meta.ts index cfd17050a7..b03ade325c 100644 --- a/src/pages/learn/_meta.ts +++ b/src/pages/learn/_meta.ts @@ -27,5 +27,9 @@ export default { performance: "", security: "", federation: "", + "-- 3": { + type: "separator", + title: "GraphQL over HTTP", + }, "debug-errors": "Common `graphql-http` Errors", } From be96f3bd514d72855a38fcb8d22687682dd28dc3 Mon Sep 17 00:00:00 2001 From: Sarah Sanders <88458517+sarahxsanders@users.noreply.github.com> Date: Mon, 9 Jun 2025 19:15:38 -0400 Subject: [PATCH 03/12] Update src/pages/learn/debug-errors.mdx Co-authored-by: Benjie --- src/pages/learn/debug-errors.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/pages/learn/debug-errors.mdx b/src/pages/learn/debug-errors.mdx index 97ecb3b740..693988198a 100644 --- a/src/pages/learn/debug-errors.mdx +++ b/src/pages/learn/debug-errors.mdx @@ -39,7 +39,7 @@ and may allow `GET` for queries. ### Common causes - Sending a `PUT` or `DELETE` request instead of `POST` or `GET` -- Sending a `GET` request for a mutation +- Sending a `GET` request for a mutation, or to a server that only supports `POST` requests ### How to debug From 4043c616e70e4bfd3b3ebcb61380963b9722b757 Mon Sep 17 00:00:00 2001 From: Sarah Sanders <88458517+sarahxsanders@users.noreply.github.com> Date: Mon, 9 Jun 2025 19:15:47 -0400 Subject: [PATCH 04/12] Update src/pages/learn/debug-errors.mdx Co-authored-by: Benjie --- src/pages/learn/debug-errors.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/pages/learn/debug-errors.mdx b/src/pages/learn/debug-errors.mdx index 693988198a..d582992ab7 100644 --- a/src/pages/learn/debug-errors.mdx +++ b/src/pages/learn/debug-errors.mdx @@ -107,7 +107,7 @@ Something went wrong on the server. ### What it means -The HTTP layer succeeded, but the GraphQL response contains errors. +The HTTP layer succeeded, but the GraphQL request produced errors. ### Common causes From 6beed82a682b23816d8514bcf42f3c549bf4eb10 Mon Sep 17 00:00:00 2001 From: Sarah Sanders <88458517+sarahxsanders@users.noreply.github.com> Date: Mon, 9 Jun 2025 19:15:58 -0400 Subject: [PATCH 05/12] Update src/pages/learn/debug-errors.mdx Co-authored-by: Benjie --- src/pages/learn/debug-errors.mdx | 1 - 1 file changed, 1 deletion(-) diff --git a/src/pages/learn/debug-errors.mdx b/src/pages/learn/debug-errors.mdx index d582992ab7..673a5054ee 100644 --- a/src/pages/learn/debug-errors.mdx +++ b/src/pages/learn/debug-errors.mdx @@ -121,7 +121,6 @@ Check the `errors` array in the response body. A typical response looks like: ```json { - "data": null, "errors": [ { "message": "Cannot query field \"foo\" on type \"Query\".", From a2b02b1df1d45a9afe18e8c777b1d4700fa48331 Mon Sep 17 00:00:00 2001 From: Sarah Sanders <88458517+sarahxsanders@users.noreply.github.com> Date: Mon, 9 Jun 2025 19:16:08 -0400 Subject: [PATCH 06/12] Update src/pages/learn/debug-errors.mdx Co-authored-by: Benjie --- src/pages/learn/debug-errors.mdx | 1 + 1 file changed, 1 insertion(+) diff --git a/src/pages/learn/debug-errors.mdx b/src/pages/learn/debug-errors.mdx index 673a5054ee..6885397810 100644 --- a/src/pages/learn/debug-errors.mdx +++ b/src/pages/learn/debug-errors.mdx @@ -114,6 +114,7 @@ The HTTP layer succeeded, but the GraphQL request produced errors. - Querying a field that doesn't exist - Passing incorrect arguments to a field - Violating schema constraints, such as non-nullability +- Runtime errors during execution ### How to debug From 26f08b76aef67e3e9293b895c89e004ee7226b0f Mon Sep 17 00:00:00 2001 From: Sarah Sanders <88458517+sarahxsanders@users.noreply.github.com> Date: Mon, 9 Jun 2025 19:16:24 -0400 Subject: [PATCH 07/12] Update src/pages/learn/debug-errors.mdx Co-authored-by: Benjie --- src/pages/learn/debug-errors.mdx | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/src/pages/learn/debug-errors.mdx b/src/pages/learn/debug-errors.mdx index 6885397810..c394428124 100644 --- a/src/pages/learn/debug-errors.mdx +++ b/src/pages/learn/debug-errors.mdx @@ -118,7 +118,11 @@ The HTTP layer succeeded, but the GraphQL request produced errors. ### How to debug -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: ```json { From f2c23054dbb4fb35076e15bd2cc48dfd059f13bd Mon Sep 17 00:00:00 2001 From: Sarah Sanders <88458517+sarahxsanders@users.noreply.github.com> Date: Mon, 9 Jun 2025 19:16:31 -0400 Subject: [PATCH 08/12] Update src/pages/learn/debug-errors.mdx Co-authored-by: Benjie --- src/pages/learn/debug-errors.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/pages/learn/debug-errors.mdx b/src/pages/learn/debug-errors.mdx index c394428124..6cc300b7cd 100644 --- a/src/pages/learn/debug-errors.mdx +++ b/src/pages/learn/debug-errors.mdx @@ -1,4 +1,4 @@ -# Common `graphql-http` Errors and How to Debug Them +# Common HTTP Errors and How to Debug Them When building or consuming a GraphQL API over HTTP, it's common to run into errors, especially during development. Understanding how to recognize and resolve these issues From 04fb26fa8e7ff1626d8cf213379eb46662989b99 Mon Sep 17 00:00:00 2001 From: Sarah Sanders <88458517+sarahxsanders@users.noreply.github.com> Date: Mon, 9 Jun 2025 19:16:43 -0400 Subject: [PATCH 09/12] Update src/pages/learn/debug-errors.mdx Co-authored-by: Benjie --- src/pages/learn/debug-errors.mdx | 8 +++----- 1 file changed, 3 insertions(+), 5 deletions(-) diff --git a/src/pages/learn/debug-errors.mdx b/src/pages/learn/debug-errors.mdx index 6cc300b7cd..8c6d28920f 100644 --- a/src/pages/learn/debug-errors.mdx +++ b/src/pages/learn/debug-errors.mdx @@ -4,11 +4,9 @@ When building or consuming a GraphQL API over HTTP, it's common to run into errors, especially during development. Understanding how to recognize and resolve these issues can save you time and frustration. -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. ## `400 Bad Request`: Syntax or parse errors From 4bbc7486c3a2c1ac4e7f11d103e23288892a4037 Mon Sep 17 00:00:00 2001 From: Sarah Sanders <88458517+sarahxsanders@users.noreply.github.com> Date: Mon, 9 Jun 2025 19:16:49 -0400 Subject: [PATCH 10/12] Update src/pages/learn/_meta.ts Co-authored-by: Benjie --- src/pages/learn/_meta.ts | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/pages/learn/_meta.ts b/src/pages/learn/_meta.ts index b03ade325c..f5c7a1887b 100644 --- a/src/pages/learn/_meta.ts +++ b/src/pages/learn/_meta.ts @@ -31,5 +31,5 @@ export default { type: "separator", title: "GraphQL over HTTP", }, - "debug-errors": "Common `graphql-http` Errors", + "debug-errors": "Common GraphQL over HTTP Errors", } From d1055906c6b552aecc554aa440a23f90194d062c Mon Sep 17 00:00:00 2001 From: sarahxsanders Date: Mon, 9 Jun 2025 19:29:45 -0400 Subject: [PATCH 11/12] feedback: add +json media type --- src/pages/learn/debug-errors.mdx | 41 ++++++++++++++++++++++++-------- 1 file changed, 31 insertions(+), 10 deletions(-) diff --git a/src/pages/learn/debug-errors.mdx b/src/pages/learn/debug-errors.mdx index 8c6d28920f..5fbd65d499 100644 --- a/src/pages/learn/debug-errors.mdx +++ b/src/pages/learn/debug-errors.mdx @@ -4,9 +4,12 @@ When building or consuming a GraphQL API over HTTP, it's common to run into errors, especially during development. Understanding how to recognize and resolve these issues can save you time and frustration. -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. +This guide outlines common HTTP and GraphQL errors, what they mean, and how to debug them +effectively. It follows the recommendations of the +[GraphQL over HTTP spec (draft)](https://graphql.github.io/graphql-over-http/draft/), +which standardizes how GraphQL works over HTTP, including request formats, status codes, +and media types. Keep in mind that implementations may vary, so treat this as a general guide rather +than a definitive reference. ## `400 Bad Request`: Syntax or parse errors @@ -25,7 +28,7 @@ or the JSON body isn't valid. - Validate your JSON body using a linter or formatter. - Make sure you're sending a `POST` request with a `Content-Type: application/json` header. -- Verify that the GraphQL query is syntactically correct. Use an IDE or a linter to verify it. +- Check your GraphQL query for syntax errors. Use an IDE or linter to verify it. ## `405 Method Not Allowed`: Wrong HTTP Method @@ -105,7 +108,7 @@ Something went wrong on the server. ### What it means -The HTTP layer succeeded, but the GraphQL request produced errors. +The HTTP layer succeeded, but the GraphQL operation produced errors. ### Common causes @@ -116,11 +119,11 @@ The HTTP layer succeeded, but the GraphQL request produced errors. ### How to debug -Check the `errors` array in the response body. +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 due to +invalid input, access denial, or a bug in server logic. -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: +If there's no `data` field, the request likely failed during validation. For example: ```json { @@ -133,4 +136,22 @@ If the response does not include a `data` property it's likely there was a mista } ``` -Compare your query against the schema using introspection or an IDE. \ No newline at end of file +Use introspection or an IDE to verify your query matches the schema. + +## Understanding GraphQL response formats + +Most GraphQL servers return responses using the `application/json` media type. However, +the [GraphQL over HTTP spec](https://graphql.github.io/graphql-over-http/draft/) recommends +using a more specific type: `application/graphql-response+json`. + +This media type identifies the payload as a GraphQL response and helps clients +distinguish it from other types of JSON. + +### What to know + +- Servers may respond with `application/graphql-response+json` instead of +`application/json`. +- Clients can request this media type using the `Accept` header: `Accept: application/graphql-response+json` +- This content type is optional, but support for it is growing. +- If your client uses content negotiation, ensure your server can response with the appropriate +type or fallback to `application/json`. From 176d140cf82c3e5d294a3d275c265e74b4c5824a Mon Sep 17 00:00:00 2001 From: sarahxsanders Date: Tue, 10 Jun 2025 19:58:06 -0400 Subject: [PATCH 12/12] fix: remove 415 and 422 and add disclaimer --- src/pages/learn/debug-errors.mdx | 52 ++++++++------------------------ 1 file changed, 13 insertions(+), 39 deletions(-) diff --git a/src/pages/learn/debug-errors.mdx b/src/pages/learn/debug-errors.mdx index 5fbd65d499..4e8ea3abc8 100644 --- a/src/pages/learn/debug-errors.mdx +++ b/src/pages/learn/debug-errors.mdx @@ -16,7 +16,7 @@ than a definitive reference. ### What it means The server couldn't parse your request. Either the GraphQL query string is malformed, -or the JSON body isn't valid. +or the JSON body isn't valid. This is the primary error status recommended by the GraphQL over HTTP specification. ### Common causes @@ -49,44 +49,6 @@ and may allow `GET` for queries. - Refer to the [GraphQL over HTTP spec](https://graphql.github.io/graphql-over-http/draft/) to confirm method support. -## `415 Unsupported Media Type` - -### What it means - -The server doesn't understand the request's `Content-Type`. - -### Common causes - -- Sending a GraphQL query with `Content-Type: text/plain` or another unsupported type -- Omitting the `Content-Type` header in a `POST` request - -### How to debug - -- Set the header explicitly: `Content-Type: application/json`. -- If you're using `application/graphql`, verify your server supports it. This content type -is optional. - -## `422 Unprocessable Entity`: Missing or invalid `query` - -### What it means - -The server received the request, but the `query` field was missing or invalid. - -### Common causes - -- Sending `{}` with no `query` key -- Sending variables or an operation name without a query - -### How to debug - -Always include a `query` field in your request body. For example: - -```json -{ - "query": "{ user(id: 1) { name } }" -} -``` - ## `500 Internal Server Error`: Unexpected server failures ### What it means @@ -138,6 +100,18 @@ If there's no `data` field, the request likely failed during validation. For exa Use introspection or an IDE to verify your query matches the schema. +## Implementation-specific status codes + +Some GraphQL server implementations may use additional HTTP status codes that are not explicitly recommended +by the specification. These vary by implementation. + +- `415 Unsupported Media Type`: The server doesn't understand the request's `Content-Type`. This can occur +when a GraphQL query is sent with `Content-Type: text/plain` or another unsupported type. +- `422 Unprocessable Entity`: Some implementations use this for GraphQL validation errors instead of `200` + errors array. + +These error codes are not recommended by the specification for most cases. Different GraphQL servers handle +validation errors differently. When in doubt, use error codes supported by the specification. + ## Understanding GraphQL response formats Most GraphQL servers return responses using the `application/json` media type. However,