gatsbyjs/gatsby · error

Plugin ${name} is not compatible with your gatsby version ${

Error message

Plugin ${name} is not compatible with your gatsby version ${gatsbyVersion} - It requires gatsby@${gatsbyPeerDependency}

What it means

Peer-dependency check during plugin resolution: the plugin's package.json declares peerDependencies.gatsby that the currently installed gatsby version does not satisfy (semver, prereleases included). The plugin may use APIs missing in your version; the warning names both versions so you can align them.

Source

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

  }

  return flattenedPlugins
}

export function warnOnIncompatiblePeerDependency(
  name: string,
  packageJSON: PackageJson
): void {
  // Note: In the future the peer dependency should be enforced for all plugins.
  const gatsbyPeerDependency = _.get(packageJSON, `peerDependencies.gatsby`)
  if (
    !isWorker &&
    gatsbyPeerDependency &&
    !semver.satisfies(gatsbyVersion, gatsbyPeerDependency, {
      includePrerelease: true,
    })
  ) {
    reporter.warn(
      `Plugin ${name} is not compatible with your gatsby version ${gatsbyVersion} - It requires gatsby@${gatsbyPeerDependency}`
    )
  }
}

View on GitHub (pinned to e85d62f177)

Solutions

1. Upgrade or downgrade the plugin to a release compatible with your gatsby version (check its peerDependencies)
2. Or upgrade gatsby to the range the plugin requires
3. Run a clean install (remove node_modules and lockfile entry) so npm/yarn/pnpm enforces the peer range

When it happens

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