Depth Limiting and Query Validation

Why Nesting Is the Attack Surface

REST endpoints have fixed shapes: /friends returns one page and stops. GraphQL lets a client decide the shape at request time, and a nested list query multiplies at every level:

query {              # depth 1
  user(id: "u1") {   # depth 2
    friends {        # depth 3
      friends {      # depth 4
        friends {    # depth 5 — 5 levels of list resolvers
          name
        }
      }
    }
  }
}

If each user has 50 friends, depth 5 with an implicit page size of 50 is up to 50⁴ leaf rows before filtering — millions of resolver invocations and the database joins behind them, all from a 120-byte request. The attacker does not need credentials beyond a valid token, does not need to know your schema beyond introspection, and never touches a field you flagged as expensive individually. The cost is structural: it comes from nesting, which no per-field rate limit sees.

Depth is defined as the maximum nesting of selection sets, counted from the operation's root. The query above has depth 5. Counting has three rules that trips people up:

• Aliases do not add depth. a1: friend and a2: friend are siblings, so a document with 2,000 aliases is still depth 1 — and that is exactly the query a depth limit waves through.
• Fragments are counted where they are spread, not where they are defined. A one-line fragment spread at level 6 contributes level 6, even though its definition sits at the top of the file.
• Introspection is a query too: __schema { types { fields { type { ... } } } } is legitimately deep, so decide deliberately whether introspection is exempt or banned outright on a public endpoint.

A depth limit turns an exponential execution problem into a string comparison performed before execution starts.

Rejecting Before Execution

GraphQL servers run three phases per request: parse, validate, execute. Validation is where every rule in the spec runs, and it is pure — no resolvers are invoked, no data is touched, so a rejected query costs you microseconds of AST walking. That is why depth limits belong here rather than in a resolver guard.

import depthLimit from 'graphql-depth-limit';
import { ApolloServer } from '@apollo/server';

const server = new ApolloServer({
  schema,
  // runs with the standard spec rules; exceeding maxDepth is a validation error
  validationRules: [depthLimit(8)],
});

The library walks the operation and reports the first selection set that nests past the limit as a normal GraphQL validation error, so clients get it in errors[] with a path and you get it in metrics without instrumenting anything.

Two things to verify with your own tests rather than trusting the default:

1. Fragment spreads. Write a document whose only depth comes from a spread fragment and assert the rule counts it. A rule that measures fragment definitions instead of usages can be evaded by moving the recursion into a fragment body.
2. Which operations are walked. The rule must apply to queries, mutations, and subscriptions alike; a rule registered only for queries leaves mutation documents unrestricted.

Custom rules follow the same shape. This one caps total selected fields, which is the companion guard depth cannot provide:

import { GraphQLError } from 'graphql';

export function fieldCountLimit(max) {
  return (context) => {
    let count = 0;
    return {
      Field() {
        if (++count > max) {
          context.reportError(
            new GraphQLError('Operation selects too many fields', {
              extensions: { code: 'QUERY_TOO_COMPLEX' },
            }),
          );
        }
      },
    };
  };
}

Because validation rules see the whole document, the counter also sees fields inside fragment definitions — including definitions the operation never spreads. That conservative overcount is the right bias for a guard: better to reject a bloated document than to execute it.

What Depth Limits Do Not Catch

A depth limit of 10 still permits a query at depth 2 with 3,000 aliased fields:

query {
  a1: product(id: "p1") { price }
  a2: product(id: "p2") { price }
  # ... 2,998 more aliases
}

Depth: 1. Resolver invocations: 3,000. The aliases exist precisely because depth counts nesting, and aliases are flat. This is the alias bomb, and it is why production setups layer rules rather than shipping one:

Depth and field count together give you a cheap structural ceiling: both are O(document size) to compute and both run in validation. But neither knows that shippingEstimate calls a pricing service while id reads a column, and neither knows a list will return 10,000 rows instead of 10. That is the gap cost analysis fills — assign weights, multiply by list-size estimates, and cap a total budget. See cost analysis and budgets for the scoring model that turns these structural guards into a capacity guard.

The final layer is what you expose at all. A custom rule that rejects __schema or a specific field by name is one line of validation logic and removes an entire reconnaissance path from a public API — depth limits protect your database, field bans protect your surface area.

Depth limits are also the wrong tool for legitimate deep documents. Relay-style pages are shallow by construction (connection → edges → node), but a client rendering a deeply nested approval chain may genuinely need depth 12. Set the threshold from production traffic: measure the depth distribution of real operations, pick a limit above the 99.9th percentile, and let the rejects tell you whether a client needs a different query shape rather than a higher ceiling.