GraphQL: PersistedQueryNotFound

Quick fix

Read the commands before running them. Anything that restarts a service, deletes data or changes permissions should be tried on a non-production system first.

# This is expected once per query; the client should retry with the full text.
# Apollo Client does this automatically with createPersistedQueryLink.

# If it happens on every request:
# 1. The server's APQ cache is not shared across instances. Use Redis
# 2. The hash algorithm differs (must be sha256 of the exact query string)
# 3. A CDN is caching the GET but not the POST fallback

# Consider build-time persisted queries instead, which remove the
# round trip and let you reject unregistered operations.

How to diagnose GraphQL errors

GraphQL returns HTTP 200 with an errors array far more often than it returns a non-2xx status, so clients that only check the status code silently ignore failures. Errors split into validation (the query does not match the schema, always fixable from the schema), authorisation (per-field resolvers rejecting), and performance guards (depth and complexity limits) which exist to protect the server from expensive queries.

If the quick fix above does not resolve it, work through these steps. They apply to this whole class of error, not just to this one message, which is usually what saves the time.

1. Always inspect the errors array, not just the HTTP status. Each entry carries a path that points at the exact field that failed.
2. Validate the query against the schema locally before sending it. GraphQL IDEs and graphql-codegen catch every validation error at build time.
3. For N+1 problems, enable resolver tracing or SQL logging and count queries per request. A DataLoader that batches by key is the standard fix.
4. When you hit a depth or complexity limit, restructure the query rather than raising the limit. The limit is usually protecting the database from an unbounded traversal.
5. Check whether the error is from the gateway or the subgraph in a federated setup; the two have separate schemas and separate authorisation.

Tools worth reaching for

• GraphiQL / Apollo Sandbox
• graphql-codegen
• Apollo tracing
• DataLoader

Authoritative references

Primary documentation for this error, worth reading before applying any fix in production.

📖 apollographql.com

Related GraphQL errors

• Apollo Client: Missing field 'x' while writing result to the cacheThe normalised cache stores objects by id and typename, and the response left out a field the…
• Apollo Server: POST body missing, invalid Content-TypeApollo Server 4 does not parse request bodies itself, so the Express integration needs…
• GraphQL: Cannot return null for non-nullable fieldA resolver returned null where the schema promised a value. GraphQL then propagates the…
• GraphQL: Cannot spread fragment within itselfA fragment references itself directly or indirectly, creating a circular reference. GraphQL…
• GraphQL: Cannot use GraphQLSchema from another module or realmTwo copies of the graphql package are installed, so the schema was built with one and…
• GraphQL: Expected type X, found YA variable or argument type does not match the schema definition. For example, passing a…
• GraphQL: Max query depth exceededThe query exceeds the server's maximum allowed nesting depth. This is a security measure to…
• GraphQL: N+1 query problemEach item in a list triggers a separate database query for related data, causing performance…

See all 13 GraphQL errors →

Browse other categories

• HTTP 494xx client errors, 5xx server errors, redirects, headers and protocol problems.
• JavaScript 42npm resolution, async pitfalls, hydration, memory limits and runtime type…
• Database 41Connections, deadlocks, constraints, replication and memory limits.
• AI 35Rate limits, context windows, GPU memory and model-serving failures.
• Network 35Refused connections, timeouts, resets, MTU problems and port exhaustion.
• Python 35Imports, virtual environments, encoding, concurrency and dependency conflicts.
• Kubernetes 34CrashLoopBackOff, ImagePullBackOff, OOMKilled, RBAC, scheduling and storage.
• Docker 27Daemon connectivity, disk space, image pulls, ports and architecture mismatches.
• System 26Disk space, systemd units, file descriptors, OOM killer and scheduled jobs.
• Cloud 25IAM permissions, quotas, service limits and credential failures.
• Security 25JWT validation, CSRF, OAuth grants, SELinux, SSH host keys and CSP.
• TLS 24Untrusted authorities, expiry, hostname mismatch, chains and cipher negotiation.

Something missing or wrong?

This entry is maintained by hand. If the fix is out of date, incomplete, or you have a better one, email a correction and it will be reviewed.