gatsbyjs/gatsby · error · Error

The "layout" argument is required for "${source.url}"

Error message

The "layout" argument is required for "${source.url}"

What it means

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.

Source

Thrown at packages/gatsby-plugin-utils/src/polyfill-remote-file/graphql/gatsby-image-resolver.ts:98

export async function gatsbyImageResolver(
  source: IRemoteFileNode,
  args: IGatsbyImageDataArgs,
  actions: Actions,
  store?: Store
): Promise<{
  images: IGatsbyImageData
  layout: string
  width: number
  height: number
  backgroundColor?: string
  placeholder?: { fallback: string } | undefined
} | null> {
  if (!isImage(source)) {
    return null
  }

  if (!args.layout) {
    throw new Error(`The "layout" argument is required for "${source.url}"`)
  }

  if (!args.width && !args.height) {
    throw new Error(`
      Either the "width" or "height" argument is required for "${source.url}"
    `)
  }

  if (!args.formats) {
    args.formats = [`auto`, `webp`, `avif`]
  }

  if (!args.outputPixelDensities) {
    args.outputPixelDensities = DEFAULT_PIXEL_DENSITIES
  }

  if (!args.breakpoints) {
    args.breakpoints = DEFAULT_BREAKPOINTS

View on GitHub (pinned to 8b06340921)

Solutions

1. Ensure the GraphQL query or resolver call includes layout (e.g., layout: FIXED, FULL_WIDTH, or CONSTRAINED).
2. If customizing the schema, set a default value for the layout argument or make it non-nullable.
3. Use gatsby-plugin-image's GatsbyImage component which always passes layout automatically.
4. Check that the remote file node has a valid url field since the message references source.url.

Example fix

// before
resize: gatsbyImageResolver(source, { width: 200 })
// after
resize: gatsbyImageResolver(source, { width: 200, layout: 'fixed' })

// Validate args before calling the resolver
if (!args.layout) {
  throw new Error('layout argument is required')
}
const validLayouts = ['fixed', 'fullWidth', 'constrained']
if (!validLayouts.includes(args.layout)) {
  throw new Error(`Invalid layout: ${args.layout}. Must be one of: ${validLayouts.join(', ')}`)
}

const hasLayout = (args: unknown): args is { layout: string } =>
  typeof args === 'object' && args !== null && typeof (args as any).layout === 'string'

When it happens

Trigger: 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.

Common situations: A custom GraphQL query calls the image resolver directly without passing layout, or a schema customization removed the default value for the layout argument.

Related errors

• Either the "width" or "height" argument is required f
• Unknown format "${args.format}" was given to resize ${source
• No width or height is given to resize "${source.url}"
• Invalid plugin options for "gatsby-plugin-sitemap":
• The provided width of "${width}" is incorrect. Dimensions sh

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