gatsbyjs/gatsby · error

[gatsby-plugin-sharp]: The "failOnError" option is deprecate

Error message

[gatsby-plugin-sharp]: The "failOnError" option is deprecated. Please use "failOn" instead.

What it means

Deprecation warning raised during pluginOptionsSchema validation of gatsby-plugin-sharp: the configured options still use the legacy boolean `failOnError`, which was replaced by the `failOn` enum (e.g. 'none'/'any'/'larger'). The warning is emitted from the schema's .custom() check; the old option still maps to failOn behavior but will be removed.

Source

Thrown at packages/gatsby-plugin-sharp/src/gatsby-node.js:250

      breakpoints: Joi.array().items(Joi.number()),
      backgroundColor: Joi.string(),
      transformOptions: Joi.object(),
      tracedSVGOptions: Joi.object(),
      blurredOptions: Joi.object(),
      jpgOptions: Joi.object(),
      pngOptions: Joi.object(),
      webpOptions: Joi.object(),
      avifOptions: Joi.object(),
    }).description(
      `Default options used by gatsby-plugin-image. \nSee https://gatsbyjs.com/docs/reference/built-in-components/gatsby-plugin-image/`
    ),
  }).custom(value => {
    const shouldNotFailOnError = !value.failOnError

    if (shouldNotFailOnError) {
      // show this warning only once in main process
      if (!process.env.GATSBY_WORKER_ID) {
        console.warn(
          `[gatsby-plugin-sharp]: The "failOnError" option is deprecated. Please use "failOn" instead.`
        )
      }

      return {
        ...value,
        failOn: `none`,
      }
    }

    return {
      ...value,
    }
  })

View on GitHub (pinned to e85d62f177)

Solutions

1. Replace failOnError with failOn (e.g. failOn: "error"/"warning"/"none") in gatsby-plugin-sharp options

When it happens

Trigger: Thrown at packages/gatsby-plugin-sharp/src/gatsby-node.js:250 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/36aa36f52b4b5412. Report an issue: GitHub.