Local plugin ${pluginName} requires a package.json file

Error message

Local plugin ${pluginName} requires a package.json file

What it means

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`.

Source

Thrown at packages/gatsby/src/bootstrap/load-plugins/utils/check-local-plugin.ts:34

  if (existsSync(pluginName) || !rootDir) {
    return {
      validLocalPlugin: false,
    }
  }

  const resolvedPath = slash(path.join(rootDir, `plugins/${pluginName}`))

  if (!existsSync(resolvedPath)) {
    return {
      validLocalPlugin: false,
    }
  }

  const resolvedPackageJson = existsSync(`${resolvedPath}/package.json`)

  // package.json is a requirement for local plugins
  if (!resolvedPackageJson) {
    throw new Error(`Local plugin ${pluginName} requires a package.json file`)
  }

  return {
    validLocalPlugin: true,
    localPluginPath: resolvedPath,
  }
}

View on GitHub (pinned to 8b06340921)

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`.

Example fix

// before: plugins/my-plugin/ contains only gatsby-node.js
// after: add plugins/my-plugin/package.json
{
  "name": "my-plugin",
  "version": "1.0.0",
  "main": "index.js"
}

Defensive patterns

Strategy: validation

Validate before calling

// Check local plugins before gatsby starts.
const fs = require("fs"), path = require("path")
for (const name of fs.readdirSync("plugins")) {
  if (!fs.existsSync(path.join("plugins", name, "package.json"))) {
  throw new Error(`Local plugin ${name} is missing package.json`)
  }
}

Prevention

Scaffold local plugins from a template that includes package.json.
Keep a CI check that lists `plugins/*/package.json`.

When it happens

Trigger: Dropping a folder into `plugins/my-plugin/` that contains `gatsby-node.js`/`gatsby-ssr.js` but no `package.json`.

Common situations: Hand-creating a plugin folder; copying source files without manifest; scaffolding from a template that omits `package.json`.

Related errors

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