{"record":{"id":"17bfc0e6babe77e3","repo":"gatsbyjs/gatsby","slug":"gatsbyimagecodemod-graphql-syntax-error-in-query","errorCode":null,"errorMessage":"GatsbyImageCodemod: GraphQL syntax error in query:\n\n${query}\n\nmessage:\n\n${err}","messagePattern":"GatsbyImageCodemod: GraphQL syntax error in query:\n\n(.+?)\n\nmessage:\n\n(.+?)","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"packages/gatsby-codemods/src/transforms/gatsby-plugin-image.js","lineNumber":435,"sourceCode":"            kind: `Name`,\n            value: `layout`,\n          },\n          value: {\n            kind: `EnumValue`,\n            value: typeMapper[layout],\n          },\n        }\n\n        fixedOrFluidField.name.value = `gatsbyImageData`\n\n        fixedOrFluidField.arguments.push(typeArgument)\n        delete fixedOrFluidField.selectionSet\n        hasChanged = true\n      },\n    })\n    return { ast, hasChanged }\n  } catch (err) {\n    throw new Error(\n      `GatsbyImageCodemod: GraphQL syntax error in query:\\n\\n${query}\\n\\nmessage:\\n\\n${err}`\n    )\n  }\n}\n","sourceCodeStart":417,"sourceCodeEnd":440,"githubUrl":"https://github.com/gatsbyjs/gatsby/blob/8b06340921ffdf23125a365b9c9923690cb62ce6/packages/gatsby-codemods/src/transforms/gatsby-plugin-image.js#L417-L440","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","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."],"exampleFix":"// before: interpolated value breaks graphql parser\nexport const query = graphql`query { file { childImageSharp { ${field} } } }`\n// after: literal query\nexport const query = graphql`query { file { childImageSharp { fixed { src } } } }`","handlingStrategy":"validation","validationCode":"const { parse } = require('graphql')\ntry { parse(queryLiteral) } catch (e) {\n  console.error(`Refusing to codemod unparseable query: ${e.message}`)\n}","typeGuard":"const isParseableGraphQL = (q: string): boolean => { try { parse(q); return true } catch { return false } }","tryCatchPattern":"try {\n  await codemod.transform(file)\n} catch (e) {\n  if (/GatsbyImageCodemod: GraphQL syntax error/.test(e.message)) {\n    // fix the query manually, then re-run on this file\n  } else throw e\n}","preventionTips":["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."],"tags":["codemod","graphql","gatsby-plugin-image","migration"],"backgroundTag":null,"analyzedSha":"8b06340921ffdf23125a365b9c9923690cb62ce6","analyzedAt":"2026-08-13T02:36:21.405Z","schemaVersion":2},"datasetVersion":"2026-08-13T04:17:16.726Z"}