{"record":{"id":"c0a7669f587707f5","repo":"gatsbyjs/gatsby","slug":"something-went-wrong-when-trying-to-add-the-plugin","errorCode":null,"errorMessage":"Something went wrong when trying to add the plugins to the project: ${(e as Error).message}","messagePattern":"Something went wrong when trying to add the plugins to the project: (.+?)","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"packages/create-gatsby/src/install-plugins.ts","lineNumber":74,"sourceCode":"  } 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: ${\n        (e as Error).message\n      }`\n    )\n  }\n}\n\nexport async function installPlugins(\n  plugins: Array<string>,\n  pluginOptions: PluginConfigMap = {},\n  rootPath: string,\n  packages: Array<string>\n): Promise<void> {\n  try {\n    const gatsbyPath = resolveGatsbyPath(rootPath)\n    const installPluginCommand = resolveGatsbyCliPath(rootPath, gatsbyPath)\n\n    await addPluginsToProject(","sourceCodeStart":56,"sourceCodeEnd":92,"githubUrl":"https://github.com/gatsbyjs/gatsby/blob/8b06340921ffdf23125a365b9c9923690cb62ce6/packages/create-gatsby/src/install-plugins.ts#L56-L92","documentation":"Thrown by create-gatsby's addPluginsToProject helper when dynamically requiring the install-plugin command and invoking its exported addPlugins function fails. The wrapper rethrows the underlying Error message so the CLI surfaces a single actionable failure instead of a raw stack trace. It indicates the plugin-install step of `gatsby new` (or the create-gatsby CLI) could not register the selected starters/plugins into the new project.","triggerScenarios":"Calling addPluginsToProject(installPluginCommand, plugins, pluginOptions, rootPath, packages) where require(installPluginCommand) resolves to a module whose addPlugins export rejects or throws, OR the installPluginCommand path itself cannot be required (wrong path/missing export). Concretely: the create-gatsby flow selecting plugins whose installer package is not installed, network-offline yarn/npm add failing, or a plugin option shape mismatched from what addPlugins expects.","commonSituations":"Running `npm create gatsby` (or the create-gatsby bin) behind a flaky proxy or offline so the CMS/theme installer package fails to fetch; selecting a plugin whose install hook writes to a path without write permissions; version skew where the installer package no longer exports addPlugins; using a custom installPluginCommand pointing at a stale local file.","solutions":["Re-run `npm create gatsby` on a stable network connection and confirm the registry is reachable (npm ping / yarn info <installer-package>).","Verify the installPluginCommand value resolves to a module that exports an async addPlugins(plugins, pluginOptions, rootPath, packages) function.","Check the wrapped Error message embedded after the colon — it carries the root cause (EACCES, ENOTFOUND, missing export) and dictates the next step.","Ensure write permissions and disk space at rootPath, and that node_modules at rootPath is not locked by another process.","If using a custom/nightly installer, pin to the matching create-gatsby and installer package versions from the release notes."],"exampleFix":"// before: passing a stale installer path\nawait installPlugins(plugins, opts, rootPath, packages)\n// after: confirm the installer module exports addPlugins before delegating\nconst mod = require(installPluginCommand)\nif (typeof mod.addPlugins !== 'function') {\n  throw new Error(`${installPluginCommand} does not export addPlugins`)\n}\nawait mod.addPlugins(plugins, opts, rootPath, packages)","handlingStrategy":"try-catch","validationCode":"const mod = (() => { try { return require(installPluginCommand) } catch { return null } })()\nif (!mod || typeof mod.addPlugins !== 'function') {\n  // skip plugin install with a clear user message instead of letting addPluginsToProject throw\n}","typeGuard":"const isInstallPluginModule = (m: any): m is { addPlugins: (...a: any[]) => Promise<void> } =>\n  !!m && typeof m.addPlugins === 'function'","tryCatchPattern":"try {\n  await addPluginsToProject(cmd, plugins, opts, root, packages)\n} catch (e) {\n  // message already embeds the root cause; surface to user, do not retry blindly\n  report.panic('Plugin installation failed: ' + (e as Error).message)\n}","preventionTips":["Validate the installer module exports addPlugins before delegating.","Run create-gatsby on a verified network connection.","Pin create-gatsby and installer package versions together from release notes."],"tags":["create-gatsby","plugin-install","cli","network"],"backgroundTag":null,"analyzedSha":"8b06340921ffdf23125a365b9c9923690cb62ce6","analyzedAt":"2026-08-13T02:36:21.405Z","schemaVersion":2},"datasetVersion":"2026-08-13T04:17:16.726Z"}