{"record":{"id":"fcd816aa0f2b0f7c","repo":"gatsbyjs/gatsby","slug":"the-layout-argument-is-required-for-source-ur","errorCode":null,"errorMessage":"The \"layout\" argument is required for \"${source.url}\"","messagePattern":"The \"layout\" argument is required for \"(.+?)\"","errorType":"validation","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"packages/gatsby-plugin-utils/src/polyfill-remote-file/graphql/gatsby-image-resolver.ts","lineNumber":98,"sourceCode":"export async function gatsbyImageResolver(\n  source: IRemoteFileNode,\n  args: IGatsbyImageDataArgs,\n  actions: Actions,\n  store?: Store\n): Promise<{\n  images: IGatsbyImageData\n  layout: string\n  width: number\n  height: number\n  backgroundColor?: string\n  placeholder?: { fallback: string } | undefined\n} | null> {\n  if (!isImage(source)) {\n    return null\n  }\n\n  if (!args.layout) {\n    throw new Error(`The \"layout\" argument is required for \"${source.url}\"`)\n  }\n\n  if (!args.width && !args.height) {\n    throw new Error(`\n      Either the \"width\" or \"height\" argument is required for \"${source.url}\"\n    `)\n  }\n\n  if (!args.formats) {\n    args.formats = [`auto`, `webp`, `avif`]\n  }\n\n  if (!args.outputPixelDensities) {\n    args.outputPixelDensities = DEFAULT_PIXEL_DENSITIES\n  }\n\n  if (!args.breakpoints) {\n    args.breakpoints = DEFAULT_BREAKPOINTS","sourceCodeStart":80,"sourceCodeEnd":116,"githubUrl":"https://github.com/gatsbyjs/gatsby/blob/8b06340921ffdf23125a365b9c9923690cb62ce6/packages/gatsby-plugin-utils/src/polyfill-remote-file/graphql/gatsby-image-resolver.ts#L80-L116","documentation":"Thrown by the polyfill-remote-file gatsby-image resolver when a GraphQL image transformation is requested without the required `layout` argument. The resolver (getGatsbyImageResolver-style) needs layout (e.g., 'fixed', 'fullWidth', 'constrained') to compute correct image sizes and srcsets.","triggerScenarios":"args.layout is falsy (undefined/null/empty) when the resolver is invoked; this can happen if the GraphQL field config does not enforce layout as a non-nullable argument or a query omits it.","commonSituations":"A custom GraphQL query calls the image resolver directly without passing layout, or a schema customization removed the default value for the layout argument.","solutions":["Ensure the GraphQL query or resolver call includes layout (e.g., layout: FIXED, FULL_WIDTH, or CONSTRAINED).","If customizing the schema, set a default value for the layout argument or make it non-nullable.","Use gatsby-plugin-image's GatsbyImage component which always passes layout automatically.","Check that the remote file node has a valid url field since the message references source.url."],"exampleFix":"// before\nresize: gatsbyImageResolver(source, { width: 200 })\n// after\nresize: gatsbyImageResolver(source, { width: 200, layout: 'fixed' })","handlingStrategy":"validation","validationCode":"// Validate args before calling the resolver\nif (!args.layout) {\n  throw new Error('layout argument is required')\n}\nconst validLayouts = ['fixed', 'fullWidth', 'constrained']\nif (!validLayouts.includes(args.layout)) {\n  throw new Error(`Invalid layout: ${args.layout}. Must be one of: ${validLayouts.join(', ')}`)\n}","typeGuard":"const hasLayout = (args: unknown): args is { layout: string } =>\n  typeof args === 'object' && args !== null && typeof (args as any).layout === 'string'","tryCatchPattern":null,"preventionTips":["Always pass layout when calling image resolvers programmatically.","Prefer the GatsbyImage React component which handles layout automatically.","Make the layout argument non-nullable in custom schema customizations."],"tags":["gatsby","image","graphql","validation","resolver"],"backgroundTag":null,"analyzedSha":"8b06340921ffdf23125a365b9c9923690cb62ce6","analyzedAt":"2026-08-13T02:36:21.405Z","schemaVersion":2},"datasetVersion":"2026-08-13T04:17:16.726Z"}