gatsbyjs/gatsby · error

Please upgrade gatsby-plugin-sharp

Error message

Please upgrade gatsby-plugin-sharp

What it means

Version guard in writeImage: gatsby-plugin-sharp loaded, but its generateImageData export is falsy (an older gatsby-plugin-sharp without that API). Image writing is skipped with this warning telling the user to upgrade gatsby-plugin-sharp; a missing package instead triggers reporter.panic("Please install gatsby-plugin-sharp").

Source

Thrown at packages/gatsby-plugin-image/src/node-apis/image-processing.ts:206

export async function writeImage(
  file: FileSystemNode,
  args: ISharpGatsbyImageArgs,
  pathPrefix: string,
  reporter: Reporter,
  cache: GatsbyCache,
  filename: string
): Promise<void> {
  let generateImageData
  try {
    generateImageData = require(`gatsby-plugin-sharp`).generateImageData
  } catch (e) {
    reporter.panic(`Please install gatsby-plugin-sharp`)
  }
  try {
    const options = { file, args, pathPrefix, reporter, cache }

    if (!generateImageData) {
      reporter.warn(`Please upgrade gatsby-plugin-sharp`)
      return
    }
    // get standard set of fields from sharp
    const sharpData = await generateImageData(options)

    if (sharpData) {
      // Write the image properties to the cache
      await fs.writeJSON(filename, sharpData)
    } else {
      reporter.warn(`Could not process image ${file.relativePath}`)
    }
  } catch (e) {
    reporter.warn(`Error processing image ${file.relativePath}. \n${e.message}`)
  }
}

View on GitHub (pinned to e85d62f177)

Solutions

1. Upgrade gatsby-plugin-sharp (and gatsby-plugin-image) to matching latest versions

When it happens

Trigger: Thrown at packages/gatsby-plugin-image/src/node-apis/image-processing.ts:206 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/89741c4edb6702c9. Report an issue: GitHub.