Gatsby "Cannot find module 'gatsby'" in CI

Node could not resolve the gatsby package from node_modules when the build started. Dependencies were not installed, the install failed silently, or the cache restored a tree without gatsby.

What this error means

A gatsby build step fails immediately with "Error: Cannot find module 'gatsby'" before any pages are built, even though the package is in package.json.

Error: Cannot find module 'gatsby'
Require stack:
- /home/runner/work/site/site/node_modules/.bin/gatsby

Common causes

Dependencies were never installed

The job ran gatsby build without a successful npm ci step first, so node_modules has no gatsby.

A restored cache without node_modules

A cache hit restored package-lock metadata but not a complete node_modules, leaving the gatsby binary absent.

How to fix it

Install dependencies before building

1. Add a clean install step that uses the committed lockfile.
2. Run gatsby build only after the install completes.
3. Confirm gatsby is a dependency in package.json, not only global.

- run: npm ci
- run: npx gatsby build

Cache the lockfile, not node_modules

Cache the package manager download directory keyed on the lockfile so installs stay reproducible.

- uses: actions/setup-node@v4
  with:
    node-version: '20'
    cache: 'npm'

How to prevent it

• Always run npm ci before gatsby build in CI.
• Keep gatsby in dependencies so the lockfile installs it.
• Cache the npm download cache, not the resolved node_modules.

Related guides