gatsbyjs/gatsby · error · EmptyGraphQLTagError

BabelPluginRemoveGraphQLQueries: Unexpected empty graphql ta

Error message

BabelPluginRemoveGraphQLQueries: Unexpected empty graphql tag.

What it means

Thrown by `EmptyGraphQLTagError` (index.ts:272). After successfully parsing the graphql template literal, if `ast.definitions.length === 0` the tag contained no operation or fragment — just whitespace/comments. Gatsby has nothing to compile, so the build aborts. The error attaches `templateLoc` for source mapping.

Source

Thrown at packages/babel-plugin-remove-graphql-queries/src/index.ts:272

  if (quasis.length !== 1) {
    throw new StringInterpolationNotAllowedError(
      quasis[0].loc?.end,
      quasis[1].loc?.start
    )
  }

  const text: string = quasis[0].value.raw
  const normalizedText: string = graphql.stripIgnoredCharacters(text)

  const hash: number = murmurhash(normalizedText, 0)
  const location = quasis[0].loc as SourceLocation | null

  try {
    const ast = graphql.parse(text)

    if (ast.definitions.length === 0) {
      throw new EmptyGraphQLTagError(location)
    }
    return { ast, text: normalizedText, hash, isGlobal }
  } catch (err) {
    throw new GraphQLSyntaxError(text, err, location)
  }
}

function isUseStaticQuery(path: NodePath<CallExpression>): boolean {
  const callee = path.node.callee
  if (callee.type === `MemberExpression`) {
    const property = callee.property as Identifier
    if (property.name === `useStaticQuery`) {
      return (path.get(`callee`).get(`object`) as NodePath).referencesImport(
        `gatsby`,
        ``
      )
    }
    return false

View on GitHub (pinned to 8b06340921)

Solutions

Add a real query or fragment body inside the graphql tag.
Remove the empty graphql tag if it is unused.
Check the `templateLoc` attached to the error to find the offending file/line.

Example fix

// before
const data = useStaticQuery(graphql``)

// after
const data = useStaticQuery(graphql`
  query SiteTitle {
    site { siteMetadata { title } }
  }
`)

Defensive patterns

Strategy: validation

Validate before calling

function graphqlTagHasBody(rawText) {
  return rawText.trim().length > 0 && graphql.parse(rawText).definitions.length > 0
}

Type guard

function isNonEmptyGraphqlTag(raw) {
  const ast = graphql.parse(raw)
  return ast.definitions.length > 0
}

Try / catch

try {
  getGraphQLTag(path)
} catch (e) {
  if (e instanceof EmptyGraphQLTagError) { /* remove or fill the tag */ }
}

Prevention

Fill in graphql tags before committing scaffolds.
Use the templateLoc on the error to jump to the offending tag.
Add an ESLint rule to flag empty graphql```` tags.

When it happens

Trigger: Writing `graphql``` or `graphql` ``; leaving a placeholder graphql tag while scaffolding; accidentally stripping the query body during a refactor.

Common situations: Scaffolding a page/StaticQuery and forgetting to fill in the query; commenting out the query body but leaving the tag; copy-paste leaving an empty tag.

Related errors

AI-assisted analysis of gatsbyjs/gatsby@8b06340921 (2026-08-13). Data as JSON: /api/errors/c063312a2dabccaf. Report an issue: GitHub.