Apollo "PersistedQueryNotFound" in CI

By Daniel Zoghalchali·Latchkey

With Automatic Persisted Queries, the client first sends just a SHA-256 hash. If the server has not seen that query, it answers PERSISTED_QUERY_NOT_FOUND so the client can retry with the full text. Stuck at this error means the retry or registration is misconfigured.

What this error means

A request returns errors with message "PersistedQueryNotFound" and extensions.code PERSISTED_QUERY_NOT_FOUND, and the operation never executes in CI.

{
  "errors": [{
    "message": "PersistedQueryNotFound",
    "extensions": { "code": "PERSISTED_QUERY_NOT_FOUND" }
  }]
}

Common causes

The full query is never sent on a miss

The client is configured hash-only, or the persisted-query link is missing, so after a miss it cannot follow up with the full operation text to register it.

The registered query manifest is not deployed

With safelisted/registered persisted queries, the manifest the server reads was not published for this build, so every hash is unknown.

How to fix it

Enable the APQ link so misses retry with the body

1. Add the persisted-query link ahead of the HTTP link on the client.
2. Confirm it retries with the full query when the server returns the not-found code.
3. Verify the server has APQ enabled to cache the query on that retry.

import { createPersistedQueryLink } from '@apollo/client/link/persisted-queries';
import { sha256 } from 'crypto-hash';
const link = createPersistedQueryLink({ sha256 }).concat(httpLink);

Publish the persisted-query manifest in CI

If you safelist queries, generate and deploy the manifest as part of the build so the server recognizes the hashes.

npx generate-persisted-query-manifest
# deploy persisted-query-manifest.json with the server build

How to prevent it

• Always pair APQ with the persisted-query link that retries on a miss.
• Generate and deploy the persisted-query manifest in the same pipeline as the server.
• Keep client and server APQ hashing algorithms identical.

Frequently asked questions

Related guides

References

• GitHub Actions documentation