Troubleshoot Persisted GraphQL Queries troubleshoot-persisted-graphql-queries
The Actions Center includes the GraphQL persisted query error alert. This means that you are informed whenever one of your GraphQL persisted queries throws an error.
To help you troubleshoot and resolve such problems, we explain the most common causes of failures, and steps on how to fix them.
Changes to the Content Fragment model changes-to-content-fragment-model
A GraphQL persisted query can fail when it is based on GraphQL types that are obsolete, often due a change in the underlying Content Fragment models.
This can happen for a variety of reasons. For example, when a content model author:
- removes or renames a field
- updates the allowed models defined for a fragment reference
- unpublishes a model that is referenced by other models
- other actions and reasons
To address this, either:
- the persisted query that is failing should be updated to accommodate the change on the Content Fragment model
- or the change on the model that introduced the problem should be reverted
GraphQL endpoint not configured graphql-endpoint-not-configured
When persisted queries return the 400 or 500 error code, together with the information No suitable endpoint found, this means that no GraphQL endpoint is configured on the AEM environment.
To correct this, follow the steps for enabling and publishing your endpoint from Manage GraphQL endpoints in AEM.
Missing path in the GraphQL persisted query URL missing-path-query-url
If persisted queries return the 400 or 500 error code with the information Suffix: '/' does not contain a path, the GraphQL servlet is being called without a path suffix.
The pattern should be /graphql/execute.json/thePath.
Blocked due to IP allow list blocked-due-to-ip-allow-list
In such a case, the query returns the 405 error code.
This is not something specific to GraphQL. See the KB article 405 Error Not Allowed.
Blocked by dispatcher blocked-dispatcher
If the GraphQL endpoint returns the 404 error on publish for POST requests, it means the GraphQL queries are blocked at the dispatcher level and the endpoint needs to be manually enabled.
This should not be the case by default, but a custom dispatcher configuration might cause this issue. See more under Dispatcher - Endpoint configuration with AEM Headless.