gatsbyjs/gatsby · error

The requested ${invalidDimension} "${invalidDimension =

Error message

    The requested ${invalidDimension} "${invalidDimension === `width` ? width : height}px" for the image ${sourceMetadata.filename} was larger than the actual image ${invalidDimension} of ${sourceMetadata[invalidDimension]}px. If possible, replace the current image with a larger one.

What it means

Error " The requested ${invalidDimension} "${invalidDimension === `width` ? width : height}px" for the image ${sourceMetadata.filename} was larger than the actual image ${invalidDimension} of ${sourceMetadata[invalidDimension]}px. If possible, replace the current image with a larger one." thrown in gatsbyjs/gatsby.

Source

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

    aspectRatio = calculated.aspectRatio
  } else {
    // if we only get one value calculate the other value based on aspectRatio
    if (!width) {
      width = Math.round((height as number) * aspectRatio)
    } else {
      height = Math.round(width / aspectRatio)
    }
  }

  const presentationWidth = width // will use this for presentationWidth, don't want to lose it
  const isRequestedSizeLargerThanOriginal =
    sourceMetadata.width < width || sourceMetadata.height < (height as number)

  // If the image is smaller than requested, warn the user that it's being processed as such
  // print out this message with the necessary information before we overwrite it for sizing
  if (isRequestedSizeLargerThanOriginal) {
    const invalidDimension = sourceMetadata.width < width ? `width` : `height`
    console.warn(`
    The requested ${invalidDimension} "${
      invalidDimension === `width` ? width : height
    }px" for the image ${
      sourceMetadata.filename
    } was larger than the actual image ${invalidDimension} of ${
      sourceMetadata[invalidDimension]
    }px. If possible, replace the current image with a larger one.`)

    if (invalidDimension === `width`) {
      width = sourceMetadata.width
      height = width / aspectRatio
    } else {
      height = sourceMetadata.height
      width = height * aspectRatio
    }
  }

  const sizes = new Set<number>()

View on GitHub (pinned to e85d62f177)

Solutions

1. Supply a higher-resolution source image
2. Request smaller dimensions for the fixed remote image

When it happens

Trigger: Thrown at packages/gatsby-plugin-utils/src/polyfill-remote-file/graphql/gatsby-image-resolver.ts:517 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/4d3860156986a0ac. Report an issue: GitHub.