Apollo Server v4 static persisted queries failing after transition from automatic local mode

Direct answer

Make sure the persistedQueries plugin is explicitly registered with resolveRequest: true and that the server loads the build‑time manifest (the JSON mapping of query strings to SHA‑256 hashes) before it starts accepting requests. When this is done, the server’s de‑serialization store will contain the exact hashes the client sends, and the 'Query not found' errors disappear.

Confirmed facts from the Apollo Server v4 documentation

• Automatic local mode internally creates a temporary map; static mode does not – you must provide the map yourself.
• The plugin option resolveRequest: true tells Apollo Server to look up the hash in the static map and reject unknown hashes with PersistedQueryNotFound.
• The manifest can be supplied via the loadPersistedQueries option (or by passing the object directly to persistedQueries).
• If the manifest is missing a hash, the server will always return a 400 error, regardless of cache state or Redis population.

Steps to resolve the issue in your production setup

1. Verify the plugin registration in your server creation code:

const { ApolloServer } = require('@apollo/server');
const { expressMiddleware } = require('@apollo/server/express4');
const { PersistedQueryPlugin } = require('@apollo/server/plugin/persistedQuery');

const server = new ApolloServer({
  schema: yourSchema,
  plugins: [
    PersistedQueryPlugin({
      // <-- essential for static mode
      resolveRequest: true,
      // load the manifest generated by your client build
      loadPersistedQueries: () => require('./path/to/persistedQueries.json'),
    }),
  ],
});

2. Confirm that the manifest file contains the exact SHA‑256 hashes your client is sending (you can cross‑check a few hashes from the Apollo Studio client or from your build output).
3. Restart the Apollo Server instances so the plugin loads the manifest into the de‑serialization store at startup.
4. Check the server logs for PersistedQueryNotFound messages. If they disappear, the map is correctly synchronized.
5. If you still see errors, verify that the load balancer or reverse proxy is not stripping the request parts that carry the persisted query information:
• For GET requests, the hash is sent in the query string parameter extensions (JSON‑encoded) or via a custom header like Apollo-Require-Persisted-Query (depending on your client). Ensure the balancer forwards the full query string and does not strip unknown parameters.
• For POST requests, the hash resides in the JSON body under extensions.persistedQuery. Confirm the balancer does not parse and discard the body or rewrite the Content‑Type.
6. After confirming the balancer forwards the required data, run a quick test:

curl -X POST https://your-api.example.com/graphql \
  -H "Content-Type: application/json" \
  -d '{"extensions":{"persistedQuery":{"version":1,"sha256Hash":""}}}'

7. Expect a successful GraphQL response (not a 400 with "Persisted query not found").

One missing diagnostic detail that could change the recommendation

Are you using GET or POST to transmit the persisted query hash? The header/query‑string handling differs between the two, and the load‑balancer fix depends on knowing which transport you rely on.