gatsbyjs/gatsby · error

Plugin "${plugin.resolve}" has an "option" key in the config

Error message

Plugin "${plugin.resolve}" has an "option" key in the configuration. Did you mean "options"?

What it means

Gatsby plugin config objects use an `options` (plural) key. The loader treats an empty `options` together with a present `option` (singular) as a near-certain typo and rejects it, so the intended config is never silently ignored.

Source

Thrown at packages/gatsby/src/bootstrap/load-plugins/process-plugin.ts:28

  if (isString(plugin)) {
    const info = resolvePlugin(plugin, rootDir)

    return {
      ...info,
      pluginOptions: {
        plugins: [],
      },
    }
  }

  plugin.options = plugin.options || {}

  // Throw an error if there is an "option" key.
  if (
    isEmpty(plugin.options) &&
    !isEmpty((plugin as { option?: unknown }).option)
  ) {
    throw new Error(
      `Plugin "${plugin.resolve}" has an "option" key in the configuration. Did you mean "options"?`
    )
  }

  // Plugins can have plugins.
  if (plugin.subPluginPaths) {
    for (const subPluginPath of plugin.subPluginPaths) {
      const segments = subPluginPath.split(`.`)
      let roots: Array<any> = [plugin.options]

      let pathToSwap = segments

      for (const segment of segments) {
        if (segment === `[]`) {
          pathToSwap = pathToSwap.slice(0, pathToSwap.length - 1)
          roots = roots.flat()
        } else {
          roots = roots.map(root => root[segment])

View on GitHub (pinned to 8b06340921)

Solutions

1. Rename the `option` key to `options` in the plugin entry.
2. Confirm the plugin's README for the exact key name before re-running.

Example fix

// before
{ resolve: `gatsby-plugin-google-analytics`, option: { trackingId: `UA-1` } }
// after
{ resolve: `gatsby-plugin-google-analytics`, options: { trackingId: `UA-1` } }

// Validate gatsby-config plugin entries before booting.
function validatePlugins(plugins) {
  for (const p of plugins) {
  if (typeof p === "object" && p && "option" in p && !("options" in p)) {
  throw new Error(`Plugin ${p.resolve} uses "option" — did you mean "options"?`)
  }
  }
}

When it happens

Trigger: A `gatsby-config.js` entry like `{ resolve: "gatsby-plugin-x", option: { trackingId: "..." } }` (singular, and no `options`).

Common situations: Copy-paste from outdated docs/examples; muscle memory from libraries that use a singular `option`.

Related errors

• Neither "cache" or "getCache" was passed. getCache must be f
• createNodeId must be a function, was ${typeof createNodeId}
• createNode must be a function, was ${typeof createNode}
• Neither "cache" or "getCache" was passed. getCache must be f
• Local plugin ${pluginName} requires a package.json file

AI-assisted analysis of gatsbyjs/gatsby@8b06340921 (2026-08-13). Data as JSON: /api/errors/63a9fca9c753d68c. Report an issue: GitHub.