gatsbyjs/gatsby · error

[gatsby-source-contentful] Invalid image format "${toFormat}

Error message

[gatsby-source-contentful] Invalid image format "${toFormat}". Supported types are jpg, png, webp and avif"

What it means

In generateImageSource, the requested toFormat from gatsby-plugin-image transform options is checked against the set of formats Contentful's Image API supports (jpg, png, webp, avif). It fires when an image is requested with an unsupported format (e.g. gif or an invalid string); the plugin logs this warning and falls back to jpg, so builds still succeed but the output format differs from what was requested.

Source

Thrown at packages/gatsby-source-contentful/src/gatsby-plugin-image.js:235

    quality,
    cropFocus,
    backgroundColor,
    resizingBehavior,
    cornerRadius,
  } = imageTransformOptions
  // Ensure we stay within Contentfuls Image API limits
  if (width > CONTENTFUL_IMAGE_MAX_SIZE) {
    height = Math.floor((height / width) * CONTENTFUL_IMAGE_MAX_SIZE)
    width = CONTENTFUL_IMAGE_MAX_SIZE
  }

  if (height > CONTENTFUL_IMAGE_MAX_SIZE) {
    width = Math.floor((width / height) * CONTENTFUL_IMAGE_MAX_SIZE)
    height = CONTENTFUL_IMAGE_MAX_SIZE
  }

  if (!validImageFormats.has(toFormat)) {
    console.warn(
      `[gatsby-source-contentful] Invalid image format "${toFormat}". Supported types are jpg, png, webp and avif"`
    )
    return undefined
  }

  const src = createUrl(filename, {
    width,
    height,
    toFormat,
    resizingBehavior,
    background: backgroundColor?.replace(`#`, `rgb:`),
    quality,
    jpegProgressive,
    cropFocus,
    cornerRadius,
  })
  return { width, height, format: toFormat, src }
}

View on GitHub (pinned to e85d62f177)

Solutions

1. Change the image transform options to use one of jpg, png, webp, or avif.
2. Remove the explicit format option so gatsby-plugin-image picks a supported default.
3. If gif was intended, pre-convert the asset or render it outside gatsbyImageData.

When it happens

Trigger: Thrown at packages/gatsby-source-contentful/src/gatsby-plugin-image.js:235 when the library encounters an invalid state.

Common situations: See trigger scenarios.

AI-assisted analysis of gatsbyjs/gatsby@e85d62f177 (2026-08-26). Data as JSON: /api/errors/5ba8b1ada3cfcb58. Report an issue: GitHub.