gatsbyjs/gatsby · error · Error

Unknown format "${args.format}" was given to resize ${source

Error message

Unknown format "${args.format}" was given to resize ${source.url}

What it means

Thrown by the resize resolver when args.format is not in the allowedFormats list (jpg, png, webp, avif, auto). After defaulting format to 'auto', the resolver validates that the requested format is one of the supported image output formats.

Source

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

): Promise<{
  width: number
  height: number
  src: string
} | null> {
  if (!isImage(source)) {
    return null
  }

  if (!args.format) {
    args.format = `auto`
  }

  if (!args.quality) {
    args.quality = DEFAULT_QUALITY
  }

  if (!allowedFormats.includes(args.format)) {
    throw new Error(
      `Unknown format "${args.format}" was given to resize ${source.url}`
    )
  }

  if (!args.width && !args.height) {
    throw new Error(`No width or height is given to resize "${source.url}"`)
  }

  const formats = validateAndNormalizeFormats(
    [args.format],
    getImageFormatFromMimeType(source.mimeType)
  )
  const [format] = formats
  const { width, height } = calculateImageDimensions(
    source,
    args as IResizeArgs & WidthOrHeight
  )

View on GitHub (pinned to 8b06340921)

Solutions

1. Use one of the supported formats: 'jpg', 'png', 'webp', 'avif', or 'auto'.
2. Use 'jpg' (not 'jpeg') for JPEG output.
3. Use lowercase format strings — the check is case-sensitive.
4. Omit the format argument entirely to default to 'auto'.

Example fix

// before
resizeImage(source, { format: 'jpeg', width: 200 })
// after
resizeImage(source, { format: 'jpg', width: 200 })

const allowedFormats = ['jpg', 'png', 'webp', 'avif', 'auto']
if (args.format && !allowedFormats.includes(args.format)) {
  throw new Error(`Unsupported format: ${args.format}. Allowed: ${allowedFormats.join(', ')}`)
}

const ALLOWED = new Set(['jpg', 'png', 'webp', 'avif', 'auto'])
const isImageFormat = (val: unknown): val is ImageFormat =>
  typeof val === 'string' && ALLOWED.has(val)

When it happens

Trigger: args.format is set to a value outside allowedFormats (e.g., 'gif', 'tiff', 'jpeg', or a typo like 'webP'), triggering the includes() check to fail.

Common situations: A query passes format: 'jpeg' instead of 'jpg', uses uppercase 'WEBP', or requests an unsupported format like 'gif' or 'svg'.

Related errors

• The "layout" argument is required for "${source.url}"
• No width or height is given to resize "${source.url}"
• Cannot specify both JPG and PNG formats
• Either the "width" or "height" argument is required f
• The provided width of "${width}" is incorrect. Dimensions sh

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