gatsbyjs/gatsby · error

Handler for command "${command}" is not a function. Your Gat

Error message

Handler for command "${command}" is not a function. Your Gatsby package might be corrupted, try reinstalling it and running the command again.

What it means

Thrown after `require(cmdPath)` succeeds but the resolved export is not a function. Each gatsby command module must default-export (or module.exports) a function; if the loaded file exports an object, undefined, or a non-function, the CLI considers the gatsby installation corrupted.

Source

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

    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}`)

      const cmd = require(cmdPath)
      if (cmd instanceof Function) {
        return cmd
      }

      return report.panic(
        `Handler for command "${command}" is not a function. Your Gatsby package might be corrupted, try reinstalling it and running the command again.`
      )
    } catch (err) {
      cli.showHelp()
      return report.panic(
        `There was a problem loading the local ${command} command. Gatsby may not be installed. Perhaps you need to run "npm install"?`,
        err
      )
    }
  }

  function getCommandHandler(
    command: string,
    handler?: (
      args: yargs.Arguments,
      cmd: (args: yargs.Arguments) => void
    ) => void,
    nodeEnv?: string | undefined

View on GitHub (pinned to 8b06340921)

Solutions

1. Reinstall the gatsby package cleanly: `rm -rf node_modules/gatsby && npm install gatsby`.
2. If the issue persists, wipe and reinstall everything: `rm -rf node_modules package-lock.json && npm install`.
3. Confirm the gatsby CLI version is compatible with the locally installed gatsby package version.
4. Check no local file at `./commands/<command>.js` or a similarly named module is shadowing the real command.

const cmd = require(cmdPath)
if (typeof cmd !== 'function') throw new Error('Corrupted gatsby install; reinstall')

const isCommandHandler = (v: unknown): v is (...args: any[]) => void => typeof v === 'function'

When it happens

Trigger: The command file at `node_modules/gatsby/dist/commands/<command>.js` was found and loaded, but its export is not callable. Caused by a truncated/modified gatsby package, a conflicting local file shadowing the command, or an incompatible Gatsby major version whose command contract changed.

Common situations: A botched `npm install`/`yarn` left a partial gatsby package; a manual edit to files under `node_modules/gatsby`; a version mismatch between gatsby CLI and the local gatsby package; a transpiler/bundler that rewrote the command module's exports.

Related errors

• There was a problem loading the local ${command} command. Ga
• There was a problem loading the local ${command} command. Ga
• 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/2c1ab4fdc92fc355. Report an issue: GitHub.