Contentful GraphQL Limit: Prepare Before 9 October 2026

Contentful will enforce a maximum of 40,000 expanded fragment spreads per GraphQL request from 9 October 2026. Requests above the ceiling will return HTTP 400. Contentful says most applications will not need changes, but applications that generate GraphQL documents with extensive repetition across nested fragments are the ones to investigate now.

For an affected headless website, ecommerce storefront, mobile app or static build, the failure may appear far away from the query source: a page can stop rendering, a build can fail, preview can break, or an integration can begin returning incomplete experiences. The practical job is not to rewrite every query. It is to identify the small set of generated or deeply composed documents that could cross the new boundary and reduce their blast radius before enforcement.

This guide is for Australian business owners, digital and marketing leaders, development teams and technology decision-makers who use Contentful directly or rely on an agency, support partner or custom application that does.

What an expanded fragment spread means

Fragments are reusable groups of GraphQL fields. They help teams avoid duplicating the same field list across page types, components and applications. The risk emerges when fragments include other fragments and the same nested graph is referenced repeatedly. Contentful will evaluate the fragment usages after those nested references are resolved.

Imagine a page query that requests many modular content blocks. Each block fragment may include a shared image fragment, link fragment, metadata fragment and tracking fragment. A page-builder query generator may then repeat those blocks across unions, locales, navigation, recommendations or preview variants. The source document can look organised while the expanded graph becomes very large.

That distinction matters because three Contentful controls answer different questions:

Contentful states that the new fragment ceiling is independent of a space's query-complexity allowance. Automatic persisted queries can help eligible plans with payload size and network transfer, but persistence or minification should not be treated as proof that a deeply repeated fragment graph is safe. The executed document still needs to comply with the new expansion rule.

Start with a complete caller inventory

The highest-risk omission is testing the main website while forgetting another system that generates a different document. Build an inventory around deployed behaviour, not repository names.

For each caller, record the repository and owner, framework or SDK, Contentful space and environment, delivery or preview endpoint, deployment route, query-generation step, monitoring location and rollback contact. If a former agency owns the build pipeline or query registry, treat access recovery as part of the migration rather than waiting for an incident.

Reduce risky queries without hiding the problem

If a document is close to or above the threshold, simplify the graph in ways that also improve maintainability.

• Split unrelated page concerns. Navigation, footer, recommendations and below-the-fold modules do not always need to be fetched in one operation.
• Remove duplicate fragment paths. Generated unions can request the same shared fragment through many branches even when a smaller common selection is sufficient.
• Limit page-builder breadth. Query the component types and fields a route can actually render instead of a universal fragment covering the whole content model.
• Load optional experiences separately. Personalisation, related content or large collections can use a second request when the customer journey allows it.
• Use explicit pagination and bounded collections. This primarily manages query complexity and response work, but it also keeps large all-purpose documents from accumulating unrelated concerns.
• Keep persisted-query registries current. When documents change, ensure deployed clients, server caches and registries agree on the new operation.

Do not merely rename fragments, remove whitespace or switch from POST to persisted execution. Those changes can reduce payload size without changing the expanded graph. The goal is fewer repeated fragment usages in the executed operation.

Questions to ask your developer or support partner

• Which live websites, mobile apps, preview tools, builds and integrations call Contentful GraphQL?
• Can you show the final generated document and expanded-fragment count for every production operation?
• Which operations have the least headroom below 40,000, and what customer journeys depend on them?
• Does CI block new or changed queries before they reach the vendor ceiling?
• Have delivery, preview, locales, page-builder routes and persisted-query versions all been tested?
• What application rollback is available if a simplified query introduces missing content?
• Will production monitoring identify the rejected operation and responsible team?
• Who owns Contentful API-change review after 9 October?

A credible answer includes an inventory, reproducible counts, test evidence and named ownership. “Most Contentful sites are unaffected” is useful context, but it is not evidence about your deployed applications.