gatsbyjs/gatsby · error

gatsby <${command}> can only be run for a gatsby site. Eithe

Error message

gatsby <${command}> can only be run for a gatsby site.
Either the current working directory does not contain a valid package.json or 'gatsby' is not specified as a dependency

What it means

Thrown by `resolveLocalCommand` when `isLocalSite` is false. `isLocalGatsbySite()` requires `./package.json` and looks for a `gatsby` entry in `dependencies` or `devDependencies`; if either is missing the directory is treated as not a Gatsby site. Most gatsby subcommands (develop, build, serve) are local-only and refuse to run otherwise.

Source

Thrown at packages/gatsby-cli/src/create-cli.ts:66

  }

  function getLocalGatsbyMajorVersion(): number | undefined {
    const version = getLocalGatsbyVersion()

    if (version) {
      return Number(version.split(`.`)[0])
    }

    return undefined
  }

  function resolveLocalCommand(
    command: string
  ): ((...args: Array<unknown>) => void) | never {
    if (!isLocalSite) {
      cli.showHelp()
      report.verbose(`current directory: ${directory}`)
      return report.panic(
        `gatsby <${command}> can only be run for a gatsby site.\n` +
          `Either the current working directory does not contain a valid package.json or ` +
          `'gatsby' is not specified as a dependency`
      )
    }

    try {
      const cmdPath =
        resolveCwd.silent(`gatsby/dist/commands/${command}`) ||
        // Old location of commands
        resolveCwd.silent(`gatsby/dist/utils/${command}`)
      if (!cmdPath)
        return report.panic(
          `There was a problem loading the local ${command} command. Gatsby may not be installed in your site's "node_modules" directory. Perhaps you need to run "npm install"? You might need to delete your "package-lock.json" as well.`
        )

      report.verbose(`loading local command from: ${cmdPath}`)

View on GitHub (pinned to 8b06340921)

Solutions

1. `cd` into the directory containing the project `package.json`.
2. Confirm `package.json` lists `gatsby` under `dependencies` or `devDependencies` (case-sensitive).
3. If missing, install gatsby: `npm install gatsby` (or `yarn add gatsby`).
4. For monorepos, run the command from the package directory, not the workspace root.

Example fix

// before: package.json missing gatsby
{
  "name": "my-site",
  "dependencies": {}
}

// after
{
  "name": "my-site",
  "dependencies": { "gatsby": "^5.0.0" }
}

// Pre-flight check mirroring isLocalGatsbySite
const fs = require('fs'); const path = require('path')
function isGatsbySite(dir = process.cwd()): boolean {
  try {
    const pkg = require(path.join(dir, 'package.json'))
    return Boolean((pkg.dependencies && pkg.dependencies.gatsby) || (pkg.devDependencies && pkg.devDependencies.gatsby))
  } catch { return false }
}
if (!isGatsbySite()) throw new Error('Run inside a Gatsby site directory')

When it happens

Trigger: Running `gatsby <command>` (e.g. `gatsby develop`) in a directory whose `package.json` has no `gatsby` dependency, or in a directory with no `package.json` at all. The CLI shows help and panics.

Common situations: Wrong working directory (running from a parent folder or `~`); fresh checkout before `npm install` added gatsby; monorepo root where the site lives in a subdirectory; typo'd package name in `package.json` (e.g. `Gatsby`).

Related errors

• There was a problem loading the local ${command} command. Ga
• 11613
• Something went wrong when trying to add the plugins to the p
• 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/9971fceaa7fe5670. Report an issue: GitHub.