GraphQL

Designs, debugs, and hardens GraphQL schemas, resolvers, and clients: N+1 batching, nullability, cost limits, subscriptions, federation. Use when writing or reviewing a schema, SDL, or resolvers; when a query is slow or fires hundreds of database queries; when the response says "Cannot return null for non-nullable field", comes back with an errors array, or nulls a whole branch; when designing mutations, cursor pagination, custom scalars, unions, or input types; when an Apollo, Relay, or urql cache will not update after a mutation; when subscriptions drop or never fire; when adding depth, alias, complexity, or persisted-query limits, disabling introspection, or masking errors; when a schema change breaks clients; or when composing Apollo Federation subgraphs and entity references. Not for consuming someone else's GraphQL API (api) or for designing REST endpoints (rest-api).

User preferences and memory live in ~/Clawic/data/graphql/ (see setup.md on first use, memory-template.md for the file format). If you have data at an old location (~/graphql/ or ~/clawic/graphql/), move it to ~/Clawic/data/graphql/.

When To Use

• Writing or reviewing a schema, SDL, resolvers, mutations, or a Relay-style connection
• Diagnosing GraphQL-specific failures: N+1 query storms, non-null propagation blanking a response, partial data with errors, caches that never update
• Hardening a public or partner endpoint: depth, alias, token and complexity limits, trusted documents, introspection policy, error masking
• Evolving a live schema without breaking clients: deprecation, breaking-change checks in CI, field usage telemetry
• Splitting or composing a graph: federation subgraphs, entity keys, reference resolvers
• Not for calling somebody else's GraphQL API (their rate limits, their cursors, their auth) — that is api; not for REST resource design — that is rest-api

Quick Reference

Situation	Play
One list query fires hundreds of SQL statements	A per-request DataLoader on every relation field (→ n-plus-one.md), never a module-level loader
Cannot return null for non-nullable field X.y	The resolver returned null or threw; the error climbs to the nearest nullable ancestor (→ Null Propagation)
Response has data AND errors	Normal. Branch on errors[].extensions.code, never on the message (→ Error Codes, errors.md)
Whole response is data: null	Every ancestor up to the root field was non-null — make one of them nullable (→ Null Propagation)
Designing a list field	Relay connection with first/after, capped at max_page_size (→ pagination.md)
Designing a mutation	<Verb><Entity>Input in, payload with the modified entity plus typed user errors out (→ mutations.md)
Public endpoint, unknown clients	Trusted documents first, cost limits second (→ security.md, Cost Model)
Deciding who may see a field	Enforce inside the resolver on the loaded row, not at the gateway (→ authorization.md)
Apollo/Relay cache stale after a mutation	The payload lacks id + __typename, or the change was a list insert (→ client.md)
Subscription never fires, or fires once and dies	Protocol mismatch, single-instance pub/sub, or expired connection token (→ subscriptions.md)
PersistedQueryNotFound in a loop	APQ hash mismatch between client, server and CDN (→ caching.md)
Same entity resolved by two services	Federation entity keys and reference resolvers (→ federation.md)
Schema change about to ship	Run the breaking-change matrix and a check against recorded operations (→ schema-evolution.md)
Types drifting from the schema	Generate them; never hand-write resolver or operation types (→ codegen.md)
"Should this be GraphQL at all"	Cost-benefit against a REST or BFF baseline (→ rest-migration.md)
Anything else	Reproduce with the smallest document that still fails, then delete one field at a time until it passes — the field you deleted names the file to open

Depth on demand: debug.md symptom→cause chains · schema.md type design · resolvers.md execution and context · n-plus-one.md batching · pagination.md connections and cursors · mutations.md writes and uploads · errors.md failure modelling · authorization.md access control · security.md DoS and disclosure · performance.md cost and latency · caching.md HTTP, CDN, APQ, entity cache · subscriptions.md realtime · federation.md multi-service graphs · client.md Apollo, Relay, urql · codegen.md typed schema and operations · testing.md tests that catch real regressions · schema-evolution.md shipping changes safely · production.md transport, timeouts, observability · rest-migration.md adoption and coexistence · commands.md toolkit.

Core Rules

1. Every field that touches a datastore goes through a per-request batch loader. Round trips without batching for a page of N parents each exposing M relation fields: 1 + N×M; with loaders: 1 + M. A page of 50 posts with author and comments is 101 queries versus 3. Build loaders in the per-request context factory — a module-level loader caches one viewer's rows and serves them to the next request (→ n-plus-one.md).
2. Nullable by default; non-null only where the value cannot fail. String! is a promise about your worst day, not your happy path. A non-null field that resolves to null nulls its nearest nullable ancestor, and [Post!]! turns one bad row into a nulled branch (→ Null Propagation).
3. Every list field is paginated and capped. Reject first > max_page_size (default 100) with a BAD_USER_INPUT error inside the resolver; clamping without saying so is only safe when clients terminate on pageInfo.hasNextPage rather than on how many items came back. An uncapped list argument is the cheapest denial of service a schema can offer.
4. Limit before you parse, then again after. Depth and complexity are validation rules that run on an already-parsed AST — a multi-megabyte document of nested braces exhausts memory in parse() before any of them execute. Ordered pipeline: body-size cap → token cap → parse → depth/alias/directive/complexity validation → execute (→ Cost Model).
5. Mutations return the modified entity, never Boolean. Payload shape: the entity (so a normalized client cache updates itself from __typename + id) plus a typed list of user errors. deleteX: Boolean forces every client into a blind refetch (→ mutations.md).
6. Mutation root fields run serially, query root fields do not. The spec guarantees document-order execution for top-level mutation selections only; sibling query fields may run in any order and concurrently. Never encode a sequence in a query, and never let a mutation's second root field depend on the first unless both are top-level siblings.
7. Recoverable failures are data; unexpected failures are the errors array. "Email already taken", "not found", "this row is not yours" → typed payload or result union, so clients handle them at compile time. Bugs, timeouts and downstream outages → throw, and let the errors array carry them (→ errors.md).
8. Mask errors in production and branch on extensions.code. The message is prose and changes without notice; the code is the contract. Stack traces, SQL fragments and the validator's "Did you mean" suggestions are schema disclosure on a public endpoint (→ security.md).
9. Deprecate on a clock set by your slowest client, remove on evidence. @deprecated(reason: "Use X") hides nothing and blocks nothing; removal is safe only after deprecation_window_days (default 90, floored by slowest_client_cycle_days) with zero operations selecting the field in usage telemetry over that same period (→ schema-evolution.md).

Null Propagation

The most misread behaviour in GraphQL. A field error nulls the field; if that field is non-null, the error climbs to the nearest nullable ancestor and nulls that instead. It never stops at a non-null boundary.

Declaration	Resolver returns null or throws	Result
author: User	null	author: null, one entry in errors
author: User!	null	The parent object becomes null; errors[].path still points at author
posts: [Post!]!, one element fails	element error	The whole list becomes null, then climbs to the parent
posts: [Post]!, one element fails	element error	That slot becomes null; the rest of the list survives
Non-null chain all the way up to a non-null root field	anything fails	data: null — the entire response is discarded

• Design consequence: non-null is for values the resolver cannot fail to produce (a NOT NULL column, a computed value). Anything crossing a network boundary is nullable.
• Null holes ([Post]) push a null check into every client loop. Prefer filtering failed elements server-side and reporting the count in extensions over shipping holes.
• Client-controlled nullability and semantic-non-null are active community proposals, not ratified spec — do not design as if the escape hatch exists (→ Where Experts Disagree).

Error Codes

extensions.code is the machine-readable contract. The codes common servers emit, and the first move for each:

Code	Meaning	First move
GRAPHQL_PARSE_FAILED	Document is not valid GraphQL	Client bug, usually a query assembled by string concatenation
GRAPHQL_VALIDATION_FAILED	Valid syntax, wrong against this schema	Client and server drifted — regenerate operations (codegen.md)
BAD_USER_INPUT	Arguments parsed, business validation failed	Fix the input; if this outcome is routine, model it as data instead (rule 7)
UNAUTHENTICATED	Missing or invalid credentials	Transport-level auth, before resolvers run
FORBIDDEN	Authenticated but not permitted	Per-row check in the resolver; choose null-versus-error deliberately (authorization.md)
PERSISTED_QUERY_NOT_FOUND	APQ hash unknown to this server	Expected once per new document; a loop means a hashing or CDN mismatch (caching.md)
INTERNAL_SERVER_ERROR	Masked unexpected failure	Correlate by request or trace id in server logs, never by message text

• Transport status is orthogonal: a completely failed execution is still commonly HTTP 200 with an errors array. A client that only checks response.ok misses every field error.
• Define your own codes as a closed enum shared with clients. Free-form code strings end up as unparseable as messages.

Cost Model

Static cost estimate for a document, computed before execution:

text

cost(field) = own_cost + multiplier × Σ cost(children)
multiplier  = the field's page-size argument (first / last / limit), default 1 for non-list fields

Worked example with own_cost = 1 for every field:

graphql

query { users(first: 50) { name posts(first: 20) { title comments(first: 10) { body } } } }

comments = 1 + 10×1 = 11 · posts = 1 + 20×(1 + 11) = 241 · users = 1 + 50×(1 + 241) = 12101. Three levels with polite-looking page sizes costs twelve thousand units — which is why a depth limit alone stops nothing.

• Calibrate the budget from your own traffic: score every operation in the registry or a week of logs, take the highest legitimate score, set the ceiling above it. A round number picked by taste either rejects real clients or admits the attack.
• Aliases multiply breadth at constant depth: a: users(first:100){…} b: users(first:100){…} repeated 50 times is one shallow, cheap-looking document. Cap aliases and total tokens alongside depth.
• Cost is an estimate; latency is truth. Pair the limiter with a per-request timeout (production.md) so a cheap-scoring but slow document still dies.

Output Gates

Before emitting a schema, resolver, or client operation, verify:

• Every list field paginated and capped at max_page_size, and non-null used only where the resolver cannot fail — no [T!]! over a partially-failable source?
• Every relation field resolved through a loader constructed per request?
• Mutations named <verb><Entity>, taking one Input, returning the modified entity plus typed user errors?
• Authorization enforced on the loaded row inside the resolver, not by operation name at the edge?
• Cost defenses on — token cap, depth, alias cap, and either a complexity budget or a trusted-document allowlist — plus error masking with a stable extensions.code for every failure a client must handle?
• Schema change run through the breaking-change matrix (schema-evolution.md) before it merges?

Configuration

User-dependent variables. Defaults apply until the user states a preference; store them in ~/Clawic/data/graphql/config.yaml.

Variable	Type	Default	Effect
server_impl	apollo-server | graphql-yoga | mercurius | graphql-js | gqlgen | strawberry | other	apollo-server	Selects the server API in every example: plugin names, context factory, error-formatting hook
client_library	apollo | relay | urql | tanstack | none	apollo	Shapes all client examples: cache configuration, fetch policies, pagination helpers in client.md
schema_style	schema-first | code-first	schema-first	Whether guidance is written as SDL or as builder code, and which direction codegen.md generates
pagination_style	relay-connection | offset | simple-list	relay-connection	The shape of every list field emitted, and which section of pagination.md applies
max_page_size	number (1-1000)	100	The cap enforced on first/last/limit in resolvers, and the multiplier ceiling in the Cost Model
error_style	errors-array | union-results	errors-array	Whether recoverable failures become a result union or a payload userErrors list (rule 7, errors.md)
dos_defense	cost-limits | trusted-documents | both	cost-limits	Which hardening security.md applies first, and whether clients must register documents before deploy
introspection_in_prod	on | off | authenticated	off	Whether production examples disable __schema, and whether field suggestions are blocked with it
deprecation_window_days	number (0-365)	90	How long a @deprecated field must show zero usage before removal is proposed (rule 9)
slowest_client_cycle_days	number (0-1095)	90	The release cycle of the slowest client surface (web bundle, mobile build, partner integration): floors deprecation_window_days and sets the minimum period usage telemetry must cover before a removal (schema-evolution.md)

Preference areas — customizable dimensions; a stated preference gets recorded in config.yaml and applied:

• Tooling: schema registry and check tool (rover, GraphQL Hive, graphql-inspector), linter (graphql-eslint), gateway (Apollo Router, Cosmo, Mesh, none) — affects schema-evolution.md, federation.md, and the CI examples
• Conventions: mutation naming, input and payload suffixes, enum casing, edges versus a nodes shortcut, global Relay IDs versus type-scoped IDs — affects every schema snippet
• Platform: runtime and deployment target (long-lived server, serverless, edge), realtime transport (WebSocket, SSE, polling), datastore and ORM — affects subscriptions.md, production.md, and the batching examples
• Limits: the calibrated ceilings themselves once measured from the operation registry — max depth, alias cap, token cap, complexity budget, response-size ceiling, and the per-layer timeout budget (resolver < request < proxy) — recorded as each is calibrated and reused instead of a round number; affects rule 4, Cost Model, security.md, production.md, and the limit tests in testing.md
• Safety posture: how aggressively to surface hardening (masking, introspection, limits) unprompted, and whether destructive schema changes need explicit confirmation before being written
• Output format: SDL only versus SDL plus resolver code, whether generated types accompany every snippet, explanation depth
• Work order: schema reviewed and agreed before resolvers are written, or both landing together
• Cadence: release cadence per client surface (web bundle, mobile build, partner integration) behind slowest_client_cycle_days, and how often the schema check, registry or log sampling, and usage review run — affects the deprecation loop and the CI examples in schema-evolution.md
• Constraints: federation forbidden, offset pagination mandated by legacy clients, fields that must never appear in operation logs or traces

Traps

Trap	Why it fails	Do instead
One DataLoader shared across requests	Its cache is keyed by id with no viewer or tenant dimension — request B reads the row loaded for request A	Construct loaders in the per-request context factory (n-plus-one.md)
Non-null everywhere "for better types"	One flaky downstream field nulls its whole ancestor chain, up to data: null	Non-null only where the resolver cannot fail (rule 2)
Depth limit as the DoS defense	Aliases and page-size arguments blow up breadth at depth 2	Token, alias and complexity budgets, or trusted documents (Cost Model)
Authorization by operation name at the gateway	Aliases, fragments and node(id:) reach the same field under other names	Check the loaded row inside the resolver (authorization.md)
totalCount: Int! on every connection	Forces a COUNT(*) on every page of every list, routinely costlier than the page itself	Nullable and opt-in, or an estimate that says it is one (pagination.md)
Int for millisecond timestamps or large counters	GraphQL Int is signed 32-bit: above 2147483647 serialization raises a field error	String or a custom scalar with a declared format; Float trades the error for lost precision (schema.md)
Custom scalar implementing only serialize	Inputs stay unvalidated — parseValue and parseLiteral are what guard the write path	Implement all three and test the literal path; variables and inline literals take different code paths
Business validation thrown into the errors array	Clients end up parsing message strings, so every wording change is a silent breaking change	Model it as data (rule 7), or a closed extensions.code enum
Mutation adds to a list, cache expected to catch up	A normalized cache updates entities it can identify; it cannot know a new node belongs in a list it already holds	Return the modified list or edge, or write an explicit cache update (client.md)
Introspection disabled, suggestions left on	Errors like "Did you mean passwordHash?" rebuild the schema field by field	Disable both together (security.md)
Resolver awaiting inside a loop over parents	Serializes what the executor would have run concurrently, on top of the N+1	Batch through the loader; if one query can serve the whole tree, project from info (resolvers.md)

Where Experts Disagree

• Errors as data versus the errors array. Result unions give clients exhaustive typed handling of every recoverable outcome; they also multiply schema surface and force fragment spreads at every call site. Default: unions for mutations with real business outcomes, errors array for reads and for anything unexpected. The line moves with error_style.
• Introspection off in production. One camp calls it theater — the schema leaks through suggestions, error messages and your own client bundles. The other treats it as one cheap layer that raises the cost of automated scanning. Both agree it is worthless alone: disable it only together with field suggestions and a document allowlist.
• Cost analysis versus trusted documents. Allowlisting registered operations makes arbitrary-query DoS structurally impossible, and is available whenever you control every client. Cost limits are the only option for a public or partner API. Running both is normal; running neither on a public endpoint is not defensible.
• Federation versus a single schema. Federation buys team autonomy and pays in query planning, cross-subgraph batching and a composition step that can fail your deploy. The trigger is organizational — separately deployed teams owning disjoint entities — not graph size (federation.md).
• Code-first versus schema-first. Code-first keeps types and resolvers together and cannot drift; schema-first keeps the contract reviewable by people who do not read your server language, which is what makes design review real. Pick per service, record it in schema_style, never mix inside one service.

Related Skills

More Clawic skills, get them at https://clawic.com/skills/graphql (install if the user confirms):

• api — consuming somebody else's GraphQL or REST API
• rest-api — designing and building REST endpoints
• authorization — the policy models behind field-level checks
• websocket — the transport underneath subscriptions

Feedback

• If useful, star it: https://clawic.com/skills/graphql
• Latest version: https://clawic.com/skills/graphql

Part of Clawic, the verified skill library. Get this skill: https://clawic.com/skills/graphql.