diff --git a/src/pages/learn/_meta.ts b/src/pages/learn/_meta.ts index ded3ef9830..b03ade325c 100644 --- a/src/pages/learn/_meta.ts +++ b/src/pages/learn/_meta.ts @@ -27,4 +27,9 @@ export default { performance: "", security: "", federation: "", + "-- 3": { + type: "separator", + title: "GraphQL over HTTP", + }, + "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