Diagnosing Gatsby Incremental Build Cache Corruption and Stale GraphQL Data

Recognizable condition

Incremental builds succeed locally but fail on CI with GraphQL schema mismatch errors, or content changes do not appear in the output despite a successful build. Typical symptoms include:

• "Cannot query field X on type Y" errors during gatsby build.
• Stale page data (old content) after a source change.
• Differences between the output of a clean build and an incremental build.

Cause / diagnostic table

Likely cause	Typical symptom	Quick diagnostic check
Committed .cache/ or public/ directories in CI	Schema mismatch or stale output	Check repository for those directories; if present, they are likely causing the issue.
Cache key missing hash of gatsby-config.js, package-lock.json or plugin versions	Incremental build uses outdated cache after config change	Inspect CI cache key definition; verify it includes those files.
Stale .cache/caches/ or .cache/redux-store.json	GraphQL type inference cache not invalidated	Compare .cache/schema.gql from a clean build vs. an incremental build.
Node version mismatch between local and CI	Build succeeds locally, fails on CI with unexpected errors	Check .nvmrc and package.json engines against CI logs.
DSG/SSR pages deployed to a static host that does not support Gatsby Functions	DSG pages return fallback or 404	Verify hosting platform supports Gatsby Functions (e.g., Netlify, Vercel, AWS Lambda@Edge).

Ordered checks

1. Run a clean build locally

   In the project root, execute:

   gatsby clean && gatsby build

   If the build succeeds and the output looks correct, proceed to step 2. If it fails, the issue is not cache‑related.

   Where to run: Local development machine with read/write access to the repo.
   Permissions: User must be able to delete .cache/ and public/.
   Risk: Deleting .cache/ forces a full rebuild, increasing build time.

2. Verify .gitignore excludes build artifacts

   Ensure the following lines exist:

   .cache/
   public/
   .public/
   

   If any are missing, add them and commit.

   Where to run: Any shell with access to the repository.

3. Inspect CI cache key

   Locate the CI configuration (e.g., .github/workflows/ci.yml, GitLab CI, Azure Pipelines). The cache key should include a hash of:

   • gatsby-config.js
   • gatsby-node.js (if present)
   • package-lock.json (or yarn.lock/pnpm-lock.yaml)
   • Versions of Gatsby plugins used.

   Example snippet for GitHub Actions:

   - uses: actions/cache@v3
     with:
       path: .cache
       key: ${{ runner.os }}-gatsby-${{ hashFiles('gatsby-config.js', 'package-lock.json', 'gatsby-node.js') }}
       restore-keys: |
         ${{ runner.os }}-gatsby-
   

   Where to run: CI pipeline definition file.
   Permissions: Ability to edit workflow files.
   Risk: An overly broad key may cause unnecessary cache misses; an overly narrow key may retain stale cache.

4. Check Node version consistency

   Confirm that the CI environment uses the same Node version as specified:

   node -v
   

   Compare against .nvmrc and the engines field in package.json.

   Where to run: CI job step (add a command to print Node version).

   Permissions: None beyond executing the command.

   Risk: Mismatched Node versions can lead to different native module behavior, affecting cache validity.
5. Compare GraphQL schema between clean and incremental builds

   Perform two builds and diff the schema files:

   # Clean build
   rm -rf public clean-build
   mkdir clean-build
   cp -r . clean-build
   cd clean-build
   npm ci
   gatsby clean
   npm run build
   cp -r public ../public-clean
   cd ..
   
   # Incremental build (without cleaning)
   rm -rf public incremental-build
   mkdir incremental-build
   cp -r . incremental-build
   cd incremental-build
   npm ci
   # Assume source unchanged
   gatsby build
   cp -r public ../public-incremental
   cd ..
   
   diff -r public-clean/.cache/schema.gql public-incremental/.cache/schema.gql
   

   If the files differ, the schema cache is not being invalidated correctly.

   Where to run: Local machine with two separate clones or temporary directories.
   Permissions: Read/write to repo and temp directories.
   Risk: Requires extra disk space and time for two builds.

6. Validate DSG/SSR deployment target

   If using gatsby-plugin-ssr or deferStaticGeneration, ensure the hosting platform runs Gatsby Functions. For static hosts (e.g., GitHub Pages, Amazon S3) these features will not work.

   Where to run: Review hosting provider documentation; test by deploying a DSG page and checking for server‑less function logs.

   Permissions: Ability to change hosting configuration. Risk: Misconfiguration leads to missing pages or fallback UI.

Fixes tied to findings

• Remove committed cache artifacts: Delete any .cache/ or public/ directories from the repository, add them to .gitignore, and push a commit that only updates the ignore file.
• Correct CI cache key: Update the cache configuration to hash gatsby-config.js, package-lock.json (or equivalent lockfile), and gatsby-node.js. Ensure the key changes when any of those files change.
• Prune stale cache directories: In CI, add a step before caching to delete .cache/caches/ and .cache/redux-store.json (or simply run gatsby clean as a precaution).
• Pin Node version: Add an .nvmrc matching the version in package.json engines and configure CI to use nvm install or the equivalent setup step.
• Ensure DSG/SSR compatibility: If the target is a static host, either disable DSG/SSR (deferStaticGeneration: false) or migrate to a platform that supports Gatsby Functions (Netlify, Vercel, AWS Amplify, etc.).
• Post‑schema‑change verification: After editing gatsby-node.js or adding/removing GraphQL fields, run gatsby build --log-pages and inspect the output for missing page data warnings.

Escalation criteria

If after performing the above checks and fixes the build still fails with GraphQL schema mismatches or stale content:

1. Verify that no custom Webpack or Babel configuration is inadvertently caching module identifiers across runs.
2. Check for version skew between Gatsby core and plugins (run npm outdated or yarn list --pattern gatsby-*).
3. Enable verbose logging (GATSBY_LOG_LEVEL=debug) and examine the logs for cache hit/miss messages.
4. Consider opening an issue in the Gatsby repository with the reproduction steps, including the cache key used and the diff of .cache/schema.gql between clean and incremental builds.

Escalate to the platform’s support team (e.g., Netlify, Vercel) only after confirming the issue persists in a completely clean local environment (gatsby clean followed by a fresh npm ci and build).