gatsbyjs/gatsby · error

Plugin "${plugin.resolve}" has an invalid options schema so

Error message

Plugin "${plugin.resolve}" has an invalid options schema so we cannot verify your configuration for it.

What it means

Startup validation warning: a plugin exports pluginOptionsSchema, but the exported value is not a valid Joi schema (Joi.isSchema failed), so gatsby cannot validate or normalize that plugin's options from gatsby-config.js. The plugin still loads with its raw, unvalidated options.

Source

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

                return schema.$_setFlag(`entry`, args.entry, { clone: true })
              }
              return schema
            },
          }
        }),
      })

      // If rootDir and plugin.parentDir are the same, i.e. if this is a plugin a user configured in their gatsby-config.js (and not a sub-theme that added it), this will be ""
      // Otherwise, this will contain (and show) the relative path
      const configDir =
        (plugin.parentDir &&
          rootDir &&
          path.relative(rootDir, plugin.parentDir)) ||
        null

      if (!Joi.isSchema(optionsSchema) || optionsSchema.type !== `object`) {
        // Validate correct usage of pluginOptionsSchema
        reporter.warn(
          `Plugin "${plugin.resolve}" has an invalid options schema so we cannot verify your configuration for it.`
        )
        return plugin
      }

      try {
        if (!optionsSchema.describe().keys.plugins) {
          // All plugins have "plugins: []"" added to their options in load.ts, even if they
          // 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) || {}

View on GitHub (pinned to e85d62f177)

Solutions

1. Fix the plugin's pluginOptionsSchema export so it returns a Joi schema built via Joi.object()...
2. Upgrade the affected plugin — a released fix may already exist
3. Manually verify the options you pass to the plugin, since they are no longer validated

When it happens

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