GraphQL was released publicly in 2015, and within a decade it went from a Facebook internal tool to a default choice for API teams everywhere. That speed explains a lot. Teams adopt it because a single endpoint and a typed schema look elegant, then discover that the same flexibility that makes GraphQL pleasant for clients makes it brutal for servers that haven’t planned for it. Most production incidents involving GraphQL trace back to a short list of repeatable mistakes, and nearly all of them are avoidable with a bit of foresight.
The N+1 Resolver Problem Nobody Warns You About
This is the classic. A client asks for a list of 50 posts, each with an author. Your resolvers fetch the posts in one query, then fetch each author individually. That’s 51 database round trips for one GraphQL request. Scale the list and the database falls over. (GraphQL)
The fix is batching and caching, usually with DataLoader or an equivalent pattern: collect all the author IDs requested during a single tick, then issue one `WHERE id IN (…)` query. The official guidance on thinking in graphs is worth reading before writing a single resolver, because it frames the mental model that prevents this mistake in the first place.
In practice, the teams that suffer most are the ones that port REST handlers directly into resolvers. A REST endpoint that returns a post with its author does one join. A GraphQL type that exposes `Post.author` as a separate field invites the N+1 pattern unless you batch. Watch your query logs during development; if you see the same SQL statement repeated dozens of times with different parameters, you’ve found it.
Skipping Depth and Complexity Limits
GraphQL lets clients ask for exactly what they want, which includes asking for something absurd. A deeply nested query on a cyclic schema can expand into millions of database calls from a single HTTP request. The spec defines how queries are structured but imposes no default limits, so protection is entirely your responsibility.
Practical defenses that actually work:
- Depth limiting. Reject queries nested beyond a sane threshold (often 7 to 10 levels for most public APIs).
- Complexity scoring. Assign a cost to each field and reject queries above a budget.
- Timeouts at the resolver level. A hard cap prevents one slow field from hanging the whole request.
- Rate limiting per client, ideally by query cost rather than raw request count.
A common mistake is adding depth limits but forgetting aliases. A client can request the same expensive field many times under different aliases in a single query, so depth alone won’t save you. Cost analysis catches that; raw depth counting does not.
Treating Nullable-by-Default as Harmless
In GraphQL, every field is nullable unless you mark it with `!`. Beginners often leave everything nullable because it “just works,” then spend months writing null checks in every client component. The schema becomes a minefield of maybe-values.
A better habit: mark fields non-null wherever the server genuinely guarantees a value, and keep nullability for cases where a missing value carries information. Be careful, though: a non-null field means an error inside it propagates upward and can null out the whole parent object. The trade-off is real, and it is why client and server engineers should both review a schema before it ships.
Leaking Internal Errors to Clients
GraphQL’s error model returns partial data alongside an `errors` array. That’s a feature, but it’s also a footgun. If your resolvers throw raw exceptions, clients may receive stack traces, SQL fragments, or internal service names. Attackers love this.
The pattern that holds up: catch errors at the resolver boundary, log the full detail server-side, and return a sanitized message with a stable error code. Clients should branch on codes, not on human-readable strings that change with every refactor.
Ignoring Authorization at the Field Level
A frequent and dangerous assumption is that once the entry point has authenticated the request, every resolver is safe. It isn’t. GraphQL exposes a graph, and different parts of that graph have different access rules. A user who can read their own profile should not automatically be able to reach another user’s private data through a relationship field.
Authorization belongs in the resolver layer (or a dedicated directive or middleware layer), applied per field or per type rather than only at the entry point. Test it by writing queries as a low-privilege user and confirming what comes back. It is surprising how often a nested field quietly bypasses the rules enforced on its parent.
Leaving Introspection and the Playground Open in Production
Introspection is wonderful in development and a gift to attackers in production. It hands over your entire schema, including fields you thought were hidden. Many teams also leave GraphQL Playground or GraphiQL exposed on public endpoints, which is effectively an open invitation to explore.
The usual recommendation is to disable introspection in production or restrict it to trusted networks, and to prefer persisted queries so clients can only send pre-approved query documents. If you’re debugging a live issue and need schema visibility, use your internal tooling rather than a public endpoint.
REST habits die hard. Teams spin up `/graphql/v2` when they need a breaking change, then maintain parallel schemas forever. GraphQL’s design intent is continuous evolution: add fields, deprecate old ones with `@deprecated`, monitor usage, and remove them once nobody calls them. (GraphQL: Learn)
The mistake here is skipping the monitoring step. Deprecation without telemetry is just a comment. You need field-level usage data to know when it’s safe to delete, and that data has to come from real traffic, not guesswork.
Over-Fetching Through Unbounded Lists
A field that returns every row in a table is a time bomb. It works fine at 100 records and collapses at 100,000. Any list field that could grow should accept pagination arguments (cursor-based is generally preferred for stability) and enforce a maximum page size server-side.
Related mistake: exposing list fields that clients rarely need but that are expensive to compute. If a field requires a heavy aggregation, consider making it a separate query with explicit arguments rather than a property hanging off a commonly fetched type.
Forgetting That Caching Works Differently
HTTP caching is straightforward: one URL, one response, cache it. GraphQL breaks that model because a single endpoint serves wildly different responses depending on the query body. Teams that assume their CDN will handle caching are usually disappointed.
What works instead: persisted queries with hashed identifiers (which restore cacheability), response-level caching keyed on query plus variables, and client-side normalized caches like Apollo Client or Relay. If you’re debugging why a stale response keeps appearing, it’s often a proxy caching by URL while ignoring the request body entirely.
Neglecting Query Cost in Client Code
The mistakes aren’t all server-side. Client developers who request entire objects “just in case” defeat the purpose of GraphQL. Every extra field costs server work, and on mobile networks it costs bytes. The discipline is to request exactly the fields a screen needs, and to split large queries into fragments that can be reused and reasoned about.
A practical habit: review queries in pull requests the way you review SQL. If a query asks for 40 fields and the component uses 6, that’s a bug waiting to be noticed.
Underestimating the Tooling Gap
GraphQL’s ecosystem is rich but uneven. Schema linting, query cost analysis, and federation tooling all exist, yet many teams ship without them because setup takes time. The cost shows up later as inconsistent naming, unreviewed schema changes, and breaking changes that slip through.
At minimum, run schema validation in CI, require schema diff reviews, and enforce naming conventions automatically. Those three steps catch a surprising share of problems before they reach production.
A Quick Comparison of Mistakes and Fixes
| Mistake | Symptom | Practical Fix |
|---|---|---|
| N+1 resolvers | Hundreds of identical DB queries per request | Batch with DataLoader |
| No depth/complexity limits | One query stalls the server | Depth caps plus cost scoring |
| Everything nullable | Null checks everywhere in clients | Non-null where guaranteed |
| Raw error leakage | Stack traces in responses | Sanitized errors with codes |
| Auth only at the entry point | Nested fields bypass rules | Per-field authorization |
| Open introspection | Schema fully exposed publicly | Disable in production |
| URL versioning | Parallel schemas forever | Deprecate and evolve |
| Unbounded lists | Slow responses as data grows | Cursor pagination with caps |
What Actually Works in Practice
The teams that avoid these traps share a few habits. They treat the schema as a product with review and versioning discipline. They instrument resolvers from day one, because you can’t fix what you can’t see. They write queries as a low-privilege user during testing. And they keep the client honest about field selection.
None of this requires exotic tooling. It requires deciding, before launch, that the schema is a contract rather than a convenience wrapper. For teams coming from REST, that mental shift is the whole game. If you’re documenting API behavior for teammates, the same clarity you’d apply when explaining how to take a screenshot on Windows to a non-technical colleague applies here: precise steps, no assumptions, no jargon shortcuts. (How to take a screenshot on a mac)
One more thing worth saying plainly: GraphQL rewards teams that read the spec. Not cover to cover, but the sections on nullability, error handling, and arguments. Most of the mistakes above are documented behavior, not obscure edge cases. The spec is dry, but it’s short, and it answers questions that otherwise get settled by argument in code review.
Conclusion
GraphQL isn’t hard because the syntax is complex; it’s hard because it removes the guardrails REST quietly provided. No fixed endpoints, no built-in pagination, no automatic caching, no default limits. Every one of those absences is a design decision you now own. The teams that succeed treat that ownership seriously: they batch their resolvers, cap their query costs, lock down introspection, authorize at the field level, and evolve the schema instead of versioning it. Do those five things and you’ll sidestep the majority of problems that send GraphQL teams back to REST in frustration.
Frequently Asked Questions
What is the N+1 problem in GraphQL?
It’s when a query for a list of items triggers one additional database call per item. A request for 50 posts with authors becomes 51 queries instead of two. Batching tools like DataLoader solve it by collecting IDs and issuing a single query.
Should introspection be disabled in production?
For most public-facing APIs, yes. Introspection exposes your full schema to anyone who asks, which helps attackers map your surface area. Internal tooling or restricted-network access can cover legitimate debugging needs.
Is GraphQL more secure than REST?
Not inherently. GraphQL shifts the security burden to you: field-level authorization, query cost limits, and error sanitization all become your responsibility. Done well, it can be more precise than REST. Done carelessly, it’s more exposed.
Why does my GraphQL API return null for a field that has data?
Usually a non-null field deeper in the tree threw an error, and the null propagated upward to the nearest nullable parent. Check the `errors` array in the response; it almost always names the failing path.
Do I need pagination on every list field?
Any list that can grow beyond a few dozen items should be paginated with a server-enforced maximum. Unbounded lists work in demos and fail in production, often without warning.
How do I know when it’s safe to remove a deprecated field?
Only when you have usage telemetry showing zero calls over a defined window. Deprecation without monitoring is a comment, not a plan. Track field usage, announce the removal, then delete.
