gatsbyjs/gatsby · error

Fragment ${spread.name.value} does not exist

Error message

Fragment ${spread.name.value} does not exist

What it means

inlineFragmentSpread looks up the fragment definition referenced by a spread node in the document being merged; not finding it means the query uses a fragment spread that was not included when assembling the batched/merged document — an internal invariant of query batching, usually a fragment-collection bug rather than user error.

Source

Thrown at packages/gatsby-source-graphql/src/batching/merge-queries.js:306

/**
 * Replaces fragment spread with inline fragment
 *
 * Example:
 *   query { ...Spread }
 *   fragment Spread on Query { bar }
 *
 * Transforms to:
 *   query { ... on Query { bar } }
 */
function inlineFragmentSpread(spread, document) {
  const fragment = document.definitions.find(
    def =>
      def.kind === Kind.FRAGMENT_DEFINITION &&
      def.name.value === spread.name.value
  )
  if (!fragment) {
    throw new Error(`Fragment ${spread.name.value} does not exist`)
  }
  const { typeCondition, selectionSet } = fragment
  return {
    kind: Kind.INLINE_FRAGMENT,
    typeCondition,
    selectionSet,
    directives: spread.directives,
  }
}

function prefixNodeName(namedNode, prefix) {
  return {
    ...namedNode,
    name: {
      ...namedNode.name,
      value: prefix + namedNode.name.value,
    },
  }

View on GitHub (pinned to e85d62f177)

Solutions

1. Ensure all referenced fragments are included in the same GraphQL document
2. Check that fragment names in spreads exactly match defined fragment names
3. Avoid manually stripping fragment definitions from documents passed to batching

When it happens

Trigger: Thrown at packages/gatsby-source-graphql/src/batching/merge-queries.js:306 when the library encounters an invalid state.

Common situations: See trigger scenarios.

AI-assisted analysis of gatsbyjs/gatsby@e85d62f177 (2026-08-26). Data as JSON: /api/errors/7ca68b841970e848. Report an issue: GitHub.