gatsbyjs/gatsby · error

Warning: there are unknown plugin options for "${plugin.reso

Error message

Warning: there are unknown plugin options for "${plugin.resolve}", configured by ${configDir}: ${validationWarnings}\nPlease open an issue at https://ghub.io/${plugin.resolve} if you believe this option is valid.

What it means

Error "Warning: there are unknown plugin options for "${plugin.resolve}", configured by ${configDir}: ${validationWarnings}\nPlease open an issue at https://ghub.io/${plugin.resolve} if you believe this option is valid." thrown in gatsbyjs/gatsby.

Source

Thrown at packages/gatsby/src/bootstrap/load-plugins/validate.ts:352

          // do not have subplugins. We add plugins to the schema if it does not exist already
          // to make sure they pass validation.
          optionsSchema = optionsSchema.append({
            plugins: Joi.array().length(0),
          })
        }

        const { value, warning } = await validateOptionsSchema(
          optionsSchema,
          (plugin.options as IPluginInfoOptions) || {}
        )

        plugin.options = value

        // Handle unknown key warnings
        const validationWarnings = warning?.details

        if (validationWarnings?.length > 0) {
          reporter.warn(
            stripIndent(`
        Warning: there are unknown plugin options for "${plugin.resolve}"${
              configDir ? `, configured by ${configDir}` : ``
            }: ${validationWarnings
              .map(error => error.path.join(`.`))
              .join(`, `)}
        Please open an issue at https://ghub.io/${
          plugin.resolve
        } if you believe this option is valid.
      `)
          )
          // We do not increment errors++ here as we do not want to process.exit if there are only warnings
        }

        // Validate subplugins if they weren't handled already
        if (!subPluginPaths.has(`plugins`) && plugin.options?.plugins) {
          const { errors: subErrors, plugins: subPlugins } =
            await validatePluginsOptions(

View on GitHub (pinned to e85d62f177)

Solutions

1. Check gatsby-config.js for the named plugin and fix/remove the unrecognized option keys listed in the warning
2. Consult the plugin's README for the correct option names (often a rename or typo)
3. If the option is genuinely supported, update the plugin so its pluginOptionsSchema includes it, or open an issue at the linked repo

When it happens

Trigger: Thrown at packages/gatsby/src/bootstrap/load-plugins/validate.ts:352 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/9b80bd802b259ccf. Report an issue: GitHub.