{"record":{"id":"00f9772e52b5768d","repo":"gatsbyjs/gatsby","slug":"could-not-find-a-suitable-version-of-gatsby-cli-p","errorCode":null,"errorMessage":"Could not find a suitable version of gatsby-cli. Please report this issue at https://www.github.com/gatsbyjs/gatsby/issues","messagePattern":"Could not find a suitable version of gatsby-cli\\. Please report this issue at https://www\\.github\\.com/gatsbyjs/gatsby/issues","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"packages/create-gatsby/src/install-plugins.ts","lineNumber":57,"sourceCode":"    try {\n      if (!installPluginCommand) {\n        // Older location\n        console.log(`looking in old place`)\n        installPluginCommand = requireResolve(`gatsby-cli/lib/plugin-add`, {\n          paths: [rootPath, path.dirname(gatsbyPath)],\n        })\n      }\n    } catch (e) {\n      // We'll error out later\n    }\n\n    if (!installPluginCommand) {\n      throw new Error()\n    }\n\n    return installPluginCommand\n  } catch (e) {\n    throw new Error(\n      `Could not find a suitable version of gatsby-cli. Please report this issue at https://www.github.com/gatsbyjs/gatsby/issues`\n    )\n  }\n}\n\nconst addPluginsToProject = async (\n  installPluginCommand: string,\n  plugins: Array<string>,\n  pluginOptions: PluginConfigMap = {},\n  rootPath: string,\n  packages: Array<string>\n): Promise<void> => {\n  try {\n    const { addPlugins } = require(installPluginCommand)\n    await addPlugins(plugins, pluginOptions, rootPath, packages)\n  } catch (e) {\n    throw new Error(\n      `Something went wrong when trying to add the plugins to the project: ${","sourceCodeStart":39,"sourceCodeEnd":75,"githubUrl":"https://github.com/gatsbyjs/gatsby/blob/8b06340921ffdf23125a365b9c9923690cb62ce6/packages/create-gatsby/src/install-plugins.ts#L39-L75","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Update gatsby-cli to match the local gatsby version: `npm i -g gatsby-cli@<matching>`.","Reinstall gatsby-cli locally: `npm i -D gatsby-cli`.","Clear npm cache and reinstall if the install looks corrupt.","As the message says, report the issue with versions if it persists after a clean install."],"exampleFix":"# before — mismatched/old gatsby-cli\nnpx create-gatsby  # global gatsby-cli lacks plugin-add path\n\n# after\nnpm install -g gatsby-cli@latest\n# or pin to match local gatsby\nnpm install -g gatsby-cli@$(node -p \"require('gatsby/package.json').version\")","handlingStrategy":"validation","validationCode":"function gatsbyCliHasPluginAdd(rootPath, gatsbyPath) {\n  for (const p of ['gatsby-cli/lib/handlers/plugin-add','gatsby-cli/lib/plugin-add']) {\n    try { require.resolve(p, { paths: [rootPath, path.dirname(gatsbyPath)] }); return true }\n    catch {}\n  }\n  return false\n}","typeGuard":"function canResolvePluginAdd(rootPath, gatsbyPath) {\n  const paths = [rootPath, path.dirname(gatsbyPath)]\n  try { require.resolve('gatsby-cli/lib/handlers/plugin-add', { paths }); return true }\n  catch { try { require.resolve('gatsby-cli/lib/plugin-add', { paths }); return true } catch { return false } }\n}","tryCatchPattern":"try {\n  resolveGatsbyCliPath(rootPath, gatsbyPath)\n} catch (e) {\n  if (/Could not find a suitable version of gatsby-cli/.test(e.message)) {\n    // upgrade/reinstall gatsby-cli, then retry\n  } else throw e\n}","preventionTips":["Keep gatsby-cli version aligned with the local gatsby version.","Reinstall gatsby-cli after major gatsby upgrades.","Prefer local gatsby-cli (npx) over global to avoid version skew."],"tags":["create-gatsby","install","gatsby-cli","version-mismatch"],"backgroundTag":null,"analyzedSha":"8b06340921ffdf23125a365b9c9923690cb62ce6","analyzedAt":"2026-08-13T02:36:21.405Z","schemaVersion":2},"datasetVersion":"2026-08-13T04:17:16.726Z"}