GatsbySortAndAggrCodemod: GraphQL syntax error in query: ${

Error message

GatsbySortAndAggrCodemod: GraphQL syntax error in query:

${query}

message:

${err}

What it means

Thrown by the sort-and-aggregation codemod when its graphql.parse/visit pass fails on a query. This transform rewrites deprecated `sort: { fields: [], order: [] }` and aggregation fields to the v4 syntax; any pre-existing GraphQL syntax error aborts the rewrite and surfaces the query plus the parse error.

Source

Thrown at packages/gatsby-codemods/src/transforms/sort-and-aggr-graphql.ts:305

                  kind: graphql.Kind.LIST,
                  values: newObjects,
                }
              : newObjects[0]
          hasChanged = true
        } else if (node.name.value === `field`) {
          if (node.value.kind !== graphql.Kind.ENUM) {
            return
          }

          // @ts-ignore read-only ...
          node.value = pathSegmentsToAst(node.value.value, `SELECT`)
          hasChanged = true
        }
      },
    })
    return { ast, hasChanged }
  } catch (err) {
    throw new Error(
      `GatsbySortAndAggrCodemod: GraphQL syntax error in query:\n\n${query}\n\nmessage:\n\n${err}`
    )
  }
}

View on GitHub (pinned to 8b06340921)

Solutions

Inspect the printed `query` to find the syntax error and its line/column.
Correct the GraphQL syntax, then re-run the codemod.
Run the transform on a smaller file subset to isolate which query fails.
Validate queries with `gatsby develop` or an independent graphql parser before codemodding.

Example fix

// before: deprecated sort syntax plus a stray brace
export const q = graphql`query { allMdx(sort: {fields: [date], order: [DESC]}} { edges { node { id } } } `
// after: v4 syntax, balanced braces
export const q = graphql`query { allMdx(sort: {fields: [date], order: [DESC]}) { edges { node { id } } } }`

Defensive patterns

Strategy: validation

Validate before calling

const { parse } = require('graphql')
files.forEach(f => { try { parse(extractQuery(f)) } catch (e) { console.warn(`${f}: ${e.message}`) } })

Type guard

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

Try / catch

try {
  await transform(file)
} catch (e) {
  if (/GatsbySortAndAggrCodemod: GraphQL syntax error/.test(e.message)) {
    // skip file, fix query manually
  } else throw e
}

Prevention

Run the codemod on small file subsets to isolate failures.
Ensure queries are valid GraphQL before migrating.
Commit between codemod runs to bisect breakage.

When it happens

Trigger: Running `npx gatsby-codemods --transform sort-and-aggr-graphql` over a file whose graphql tag literal is syntactically invalid; visiting an allX query with malformed arguments; partial edits left an unclosed selection set.

Common situations: Codemodding from Gatsby v2/v3 to v4 where the codebase has hand-written or generated queries with syntax errors; queries that built via string concatenation; old fragment definitions referencing removed types.

Related errors

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