gatsbyjs/gatsby · error

generateImageSource must be a function

Error message

generateImageSource must be a function

What it means

Thrown by generateImageData in gatsby-plugin-image's image-utils when the `generateImageSource` argument is not a function. generateImageSource is the per-plugin hook that produces per-format image source descriptors; without it the pipeline cannot create any image data, so the call is rejected before any processing.

Source

Thrown at packages/gatsby-plugin-image/src/image-utils.ts:245

    layout,
    fit,
    options,
    width,
    height,
    filename,
    reporter = { warn },
    backgroundColor,
    placeholderURL,
  } = args

  if (!pluginName) {
    reporter.warn(
      `[gatsby-plugin-image] "generateImageData" was not passed a plugin name`
    )
  }

  if (typeof generateImageSource !== `function`) {
    throw new Error(`generateImageSource must be a function`)
  }

  if (!sourceMetadata || (!sourceMetadata.width && !sourceMetadata.height)) {
    // No metadata means we let the CDN handle max size etc, aspect ratio etc
    sourceMetadata = {
      width,
      height,
      format: sourceMetadata?.format || formatFromFilename(filename) || `auto`,
    }
  } else if (!sourceMetadata.format) {
    sourceMetadata.format = formatFromFilename(filename)
  }

  const formats = new Set<ImageFormat>(args.formats)

  if (formats.size === 0 || formats.has(`auto`) || formats.has(``)) {
    formats.delete(`auto`)
    formats.delete(``)

View on GitHub (pinned to 8b06340921)

Solutions

1. Pass a function for generateImageSource that returns { [format]: { src, width, height, ... } } per requested format/width.
2. Verify the args object you pass to generateImageData includes generateImageSource (typeof === 'function').
3. Mirror the signature from gatsby-plugin-sharp or the official plugin-image CDN helpers.

Example fix

// before
await generateImageData({ filename, sourceMetadata, layout })
// after
await generateImageData({
  filename,
  sourceMetadata,
  layout,
  generateImageSource: ({ filename, width, height, format }) => ({ [format]: { src: `${filename}?w=${width}`, width, height } }),
})

if (typeof args.generateImageSource !== 'function') {
  throw new Error('generateImageSource required')
}

const hasGenerateImageSource = (a: any): a is { generateImageSource: Function } =>
  !!a && typeof a.generateImageSource === 'function'

When it happens

Trigger: Calling generateImageData({ ...args }) without supplying generateImageSource, or supplying it as a string/object/undefined. Typically happens when authoring a custom image CDN/plugin integration and forgetting to implement the hook, or when spreading an args object that omits it.

Common situations: Writing a new gatsby-plugin-image-compatible plugin and missing the generateImageSource export; passing the wrong destructured arg name; partial refactor that renamed the field; consuming an args object built upstream that dropped the function.

Related errors

• Specified dimensions for images must be positive numbers (>
• An ID must be provided when creating or setting job
• An ID must be provided when ending a job
• You must pass an object into setPluginStatus. What was passe
• The prop `fluid` or `fixed` is marked as required in `${comp

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