gatsbyjs/gatsby · error · Error

Unknown format " " was given to resize

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.

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

• Cannot specify both JPG and PNG formats
• No width or height is given to resize
• The "layout" argument is required for
• Either the "width" or "height" argument is required for
• RemoteFileNode does not have a mimeType. The field is…

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

Appendix: 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)