gatsbyjs/gatsby · error · Error

GatsbySortAndAggrCodemod: GraphQL syntax error in query

Error message

GatsbySortAndAggrCodemod: GraphQL syntax error in query:

${query}

message:

${err}

What it means

Gatsby v5 runs the `GatsbySortAndAggrCodemod` over every query to rewrite legacy `sort: { fields, order }` and aggregation `field:` syntax into the new path-object form. It wraps `graphql.visit` in try/catch; any parse/visit failure is rethrown with the offending query and the underlying error message.

Solutions

Locate the offending query (the message includes it) and fix the syntax error.
Manually migrate legacy `sort`/aggregation syntax to the v5 form.
Update the source plugin that generated the query if it is not v5-compatible.
Re-run `gatsby build`/`develop` to confirm the codemod succeeds.

Example fix

// before (legacy sort)
allX(sort: { fields: [title], order: [DESC] })
// after (v5)
allX(sort: { title: DESC })

Defensive patterns

Strategy: try-catch

Validate before calling

// Pre-validate page queries parse with graphql  before build.
const { parse, visit } = require("graphql")
function validateQuery(query) {
  try { visit(parse(query), {}) } catch (e) {
  throw new Error(`Invalid GraphQL query: ${e.message}\n${query}`)
  }
}

Try / catch

// Wrap the codemod call so one bad query is reported, not fatal.
try {
  transform(document)
} catch (e) {
  if (/GatsbySortAndAggrCodemod/.test(String(e))) {
  reportQueryError(e)
  }
  throw e
}

Prevention

Run `gatsby build` locally after upgrading to v5 to surface codemod failures early.
Migrate legacy `sort`/aggregation syntax ahead of the upgrade.
Keep source plugins current with the Gatsby major version.

When it happens

Trigger: A page/static query containing malformed GraphQL, or valid-but-unsupported legacy syntax the codemod's visitor cannot transform, thrown during `visit`.

Common situations: Upgrading to Gatsby v5 with queries that were hand-written or generated by an older plugin; fragments concatenated incorrectly producing invalid AST; queries produced by source plugins that emit deprecated aggregation syntax.

Related errors

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

Appendix: source

Thrown at packages/gatsby/src/query/transform-document.ts:135

                  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}`
    )
  }
}

export function tranformDocument(ast: graphql.DocumentNode): {
  ast: graphql.DocumentNode
  hasChanged: boolean
  error?: Error
} {
  if (_CFLAGS_.GATSBY_MAJOR === `5`) {
    try {
      return processGraphQLQuery(ast)
    } catch (error) {
      return { ast, hasChanged: false, error }
    }
  }
  return { ast, hasChanged: false }

View on GitHub (pinned to 8b06340921)