GatsbyImageCodemod: GraphQL syntax error in query: ${query}

Error message

GatsbyImageCodemod: GraphQL syntax error in query:

${query}

message:

${err}

What it means

Thrown by the GatsbyImage codemod when the graphql.parse/visit pass over a source file's query fails. It wraps the underlying parse error with the offending query text so the user can locate the bad fragment/field. The codemod migrates deprecated fixed/fluid image fields to gatsbyImageData; any pre-existing GraphQL syntax error in the file aborts the transform.

Source

Thrown at packages/gatsby-codemods/src/transforms/gatsby-plugin-image.js:435

            kind: `Name`,
            value: `layout`,
          },
          value: {
            kind: `EnumValue`,
            value: typeMapper[layout],
          },
        }

        fixedOrFluidField.name.value = `gatsbyImageData`

        fixedOrFluidField.arguments.push(typeArgument)
        delete fixedOrFluidField.selectionSet
        hasChanged = true
      },
    })
    return { ast, hasChanged }
  } catch (err) {
    throw new Error(
      `GatsbyImageCodemod: GraphQL syntax error in query:\n\n${query}\n\nmessage:\n\n${err}`
    )
  }
}

View on GitHub (pinned to 8b06340921)

Solutions

Read the `query` block printed in the message to find the syntax error location.
Fix the GraphQL syntax (unclosed brace, stray interpolation, invalid directive) before re-running the codemod.
Temporarily exclude the offending file/dir from the codemod invocation, transform the rest, then handle it manually.
Run `gatsby develop` once to confirm the query is valid before codemodding.

Example fix

// before: interpolated value breaks graphql parser
export const query = graphql`query { file { childImageSharp { ${field} } } }`
// after: literal query
export const query = graphql`query { file { childImageSharp { fixed { src } } } }`

Defensive patterns

Strategy: validation

Validate before calling

const { parse } = require('graphql')
try { parse(queryLiteral) } catch (e) {
  console.error(`Refusing to codemod unparseable query: ${e.message}`)
}

Type guard

const isParseableGraphQL = (q: string): boolean => { try { parse(q); return true } catch { return false } }

Try / catch

try {
  await codemod.transform(file)
} catch (e) {
  if (/GatsbyImageCodemod: GraphQL syntax error/.test(e.message)) {
    // fix the query manually, then re-run on this file
  } else throw e
}

Prevention

Validate graphql literals with `gatsby develop` before codemodding.
Avoid interpolated values inside graphql tags.
Run codemods on a clean git tree so failures are reversible.

When it happens

Trigger: Running `npx gatsby-codemods src` (or the gatsby-plugin-image transform) on a file whose graphql`` literal or .graphql export has invalid syntax; visiting a fragment with unparseable directives; leftover template-literal interpolation inside a graphql tag that breaks the parser.

Common situations: Codemodding a codebase that had latent GraphQL syntax errors never surfaced at runtime; mixing interpolated strings into graphql tags; partial manual edits left a query unclosed; upgrading from a Gatsby version with different GraphQL grammar.

Related errors

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