gatsbyjs/gatsby · error · GraphQLSyntaxError

BabelPluginRemoveGraphQLQueries: GraphQL syntax error in que

Error message

BabelPluginRemoveGraphQLQueries: GraphQL syntax error in query:

${documentText}

message:

${originalError}

What it means

Thrown by `GraphQLSyntaxError` (index.ts:276) when `graphql.parse(text)` itself throws inside `getGraphQLTag`. The original parse error and the offending document text are wrapped so the build can surface file location and context. The original error is preserved on `originalError` and the source location on `templateLoc`.

Source

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

      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
  }
  if ((callee as Identifier).name === `useStaticQuery`) {
    return path.get(`callee`).referencesImport(`gatsby`, ``)
  }

View on GitHub (pinned to 8b06340921)

Solutions

Read `originalError` in the message — it pinpoints the syntax problem and line/column.
Paste the query into a GraphQL linting tool or GraphiQL to find the syntax error.
Fix the syntax and rebuild.

Example fix

// before — missing closing brace
graphql`
  query {
    site { title }
`

// after
graphql`
  query {
    site { siteMetadata { title } }
  }
`

Defensive patterns

Strategy: try-catch

Validate before calling

function graphqlParses(text) {
  try { graphql.parse(text); return true } catch { return false }
}

Type guard

function isGraphQLSyntaxError(e) {
  return e instanceof GraphQLSyntaxError || /^BabelPluginRemoveGraphQLQueries: GraphQL syntax error/.test(e.message)
}

Try / catch

try {
  graphql.parse(queryText)
} catch (e) {
  // surface e to the user with line/column from originalError
}

Prevention

Validate queries in GraphiQL before committing.
Use a GraphQL ESLint plugin to catch syntax errors at lint time.
Read originalError in the wrapped message for precise diagnostics.

When it happens

Trigger: Any malformed GraphQL in a `graphql`...`` tag: missing braces, unbalanced parentheses, undefined directives, invalid field syntax, stray characters, unsupported GraphQL features.

Common situations: Hand-editing a query and breaking syntax; using GraphQL features not supported by the project's graphql version; merging queries incorrectly; trailing commas or JS-style syntax leaking into the query.

Related errors

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