{"record":{"id":"42938e3a630416b4","repo":"gatsbyjs/gatsby","slug":"local-plugin-pluginname-requires-a-package-json","errorCode":null,"errorMessage":"Local plugin ${pluginName} requires a package.json file","messagePattern":"Local plugin (.+?) requires a package\\.json file","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"packages/gatsby/src/bootstrap/load-plugins/utils/check-local-plugin.ts","lineNumber":34,"sourceCode":"  if (existsSync(pluginName) || !rootDir) {\n    return {\n      validLocalPlugin: false,\n    }\n  }\n\n  const resolvedPath = slash(path.join(rootDir, `plugins/${pluginName}`))\n\n  if (!existsSync(resolvedPath)) {\n    return {\n      validLocalPlugin: false,\n    }\n  }\n\n  const resolvedPackageJson = existsSync(`${resolvedPath}/package.json`)\n\n  // package.json is a requirement for local plugins\n  if (!resolvedPackageJson) {\n    throw new Error(`Local plugin ${pluginName} requires a package.json file`)\n  }\n\n  return {\n    validLocalPlugin: true,\n    localPluginPath: resolvedPath,\n  }\n}\n","sourceCodeStart":16,"sourceCodeEnd":42,"githubUrl":"https://github.com/gatsbyjs/gatsby/blob/8b06340921ffdf23125a365b9c9923690cb62ce6/packages/gatsby/src/bootstrap/load-plugins/utils/check-local-plugin.ts#L16-L42","documentation":"Local plugins live under `<site>/plugins/<name>/` and Gatsby requires a `package.json` in that folder to identify and load the plugin. Its absence is treated as an invalid local plugin rather than guessing an `index.js`.","triggerScenarios":"Dropping a folder into `plugins/my-plugin/` that contains `gatsby-node.js`/`gatsby-ssr.js` but no `package.json`.","commonSituations":"Hand-creating a plugin folder; copying source files without manifest; scaffolding from a template that omits `package.json`.","solutions":["Add `plugins/<name>/package.json` with at least `{ \"name\": \"...\", \"version\": \"1.0.0\", \"main\": \"index.js\" }`.","Point `main` at the file that exports the Gatsby Node/Browser APIs.","Re-run `gatsby develop`/`build`."],"exampleFix":"// before: plugins/my-plugin/ contains only gatsby-node.js\n// after: add plugins/my-plugin/package.json\n{\n  \"name\": \"my-plugin\",\n  \"version\": \"1.0.0\",\n  \"main\": \"index.js\"\n}","handlingStrategy":"validation","validationCode":"// Check local plugins before gatsby starts.\nconst fs = require(\"fs\"), path = require(\"path\")\nfor (const name of fs.readdirSync(\"plugins\")) {\n  if (!fs.existsSync(path.join(\"plugins\", name, \"package.json\"))) {\n  throw new Error(`Local plugin ${name} is missing package.json`)\n  }\n}\n","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Scaffold local plugins from a template that includes package.json.","Keep a CI check that lists `plugins/*/package.json`."],"tags":["plugins","config","filesystem","local-plugin"],"backgroundTag":null,"analyzedSha":"8b06340921ffdf23125a365b9c9923690cb62ce6","analyzedAt":"2026-08-13T02:36:21.405Z","schemaVersion":2},"datasetVersion":"2026-08-13T04:17:16.726Z"}