gatsbyjs/gatsby · error

Could not find a suitable version of gatsby-cli. Please repo

Error message

Could not find a suitable version of gatsby-cli. Please report this issue at https://www.github.com/gatsbyjs/gatsby/issues

What it means

Thrown by `resolveGatsbyCliPath` in create-gatsby (install-plugins.ts:57). It tries to resolve `gatsby-cli/lib/handlers/plugin-add` first, then the older `gatsby-cli/lib/plugin-add` location; if both fail it rethrows this generic message. The plugin-add command path moved between gatsby-cli versions, so this error indicates the installed gatsby-cli predates or omits both paths.

Source

Thrown at packages/create-gatsby/src/install-plugins.ts:57

    try {
      if (!installPluginCommand) {
        // Older location
        console.log(`looking in old place`)
        installPluginCommand = requireResolve(`gatsby-cli/lib/plugin-add`, {
          paths: [rootPath, path.dirname(gatsbyPath)],
        })
      }
    } catch (e) {
      // We'll error out later
    }

    if (!installPluginCommand) {
      throw new Error()
    }

    return installPluginCommand
  } catch (e) {
    throw new Error(
      `Could not find a suitable version of gatsby-cli. Please report this issue at https://www.github.com/gatsbyjs/gatsby/issues`
    )
  }
}

const addPluginsToProject = async (
  installPluginCommand: string,
  plugins: Array<string>,
  pluginOptions: PluginConfigMap = {},
  rootPath: string,
  packages: Array<string>
): Promise<void> => {
  try {
    const { addPlugins } = require(installPluginCommand)
    await addPlugins(plugins, pluginOptions, rootPath, packages)
  } catch (e) {
    throw new Error(
      `Something went wrong when trying to add the plugins to the project: ${

View on GitHub (pinned to 8b06340921)

Solutions

1. Update gatsby-cli to match the local gatsby version: `npm i -g gatsby-cli@<matching>`.
2. Reinstall gatsby-cli locally: `npm i -D gatsby-cli`.
3. Clear npm cache and reinstall if the install looks corrupt.
4. As the message says, report the issue with versions if it persists after a clean install.

Example fix

# before — mismatched/old gatsby-cli
npx create-gatsby  # global gatsby-cli lacks plugin-add path

# after
npm install -g gatsby-cli@latest
# or pin to match local gatsby
npm install -g gatsby-cli@$(node -p "require('gatsby/package.json').version")

function gatsbyCliHasPluginAdd(rootPath, gatsbyPath) {
  for (const p of ['gatsby-cli/lib/handlers/plugin-add','gatsby-cli/lib/plugin-add']) {
    try { require.resolve(p, { paths: [rootPath, path.dirname(gatsbyPath)] }); return true }
    catch {}
  }
  return false
}

function canResolvePluginAdd(rootPath, gatsbyPath) {
  const paths = [rootPath, path.dirname(gatsbyPath)]
  try { require.resolve('gatsby-cli/lib/handlers/plugin-add', { paths }); return true }
  catch { try { require.resolve('gatsby-cli/lib/plugin-add', { paths }); return true } catch { return false } }
}

try {
  resolveGatsbyCliPath(rootPath, gatsbyPath)
} catch (e) {
  if (/Could not find a suitable version of gatsby-cli/.test(e.message)) {
    // upgrade/reinstall gatsby-cli, then retry
  } else throw e
}

When it happens

Trigger: Installed gatsby-cli is too old (predates `lib/handlers/plugin-add`) or too new/renamed (neither path exists); a corrupted gatsby-cli install where the sub-module is missing; a global vs local gatsby-cli mismatch.

Common situations: Using a globally installed gatsby-cli that is far older than the local gatsby; partial gatsby-cli installs after a failed update; running an experimental gatsby-cli build that renamed plugin-add.

Related errors

• Could not find "gatsby" in ${rootPath}. Perhaps it wasn't in
• Something went wrong when trying to add the plugins to the p
• Did not recognize ${curr}
• starter ${starterPath} doesn't exist
• You can't create a starter from the existing directory. If y

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