ENOENT: no such file or directory, open '.cache/graphql-schema.json' during build

Answer to the exact question

No. A Gatsby production build does not require a pre-existing .cache directory when deploying from a clean backup. The build creates .cache and all required files, including .cache/graphql-schema.json, during the initial data-layer bootstrap phase.

The recommended sequence for this specific ENOENT error is to reset the internal state and rebuild from scratch:

1. Run gatsby clean. This removes public and the entire .cache directory, ensuring no stale or partially written artifacts remain from the backup.
2. Run gatsby build. Gatsby will bootstrap the data layer, generate the GraphQL schema, and populate .cache/graphql-schema.json.
3. Verify the result. Check that the file exists and is non-empty, and that the build completes without bootstrap errors.

Confirmed facts

• Gatsby 4.x and 5.x generate .cache on first build; the schema file is constructed during bootstrap from source nodes and plugins.
• gatsby clean guarantees the next build regenerates the full data layer.

Likely explanation

• The backup contains source files but no .cache. The development server can recreate artifacts on demand, but a production build that encounters a partially restored or corrupted cache state can fail before bootstrap completes.
• If a partial .cache was restored, or a CI cache from an incomplete backup is reused, the build tries to read .cache/graphql-schema.json and hits ENOENT.
• A custom plugin or script that reads the schema file directly can also trigger this error by bypassing Gatsby’s normal bootstrap logic.

Verification

After gatsby clean, confirm the directory is gone. Then build and check:

gatsby build
wc -l .cache/graphql-schema.json
gatsby info

A positive line count and a successful gatsby info output indicate the data layer initialized correctly.

Assumption: no custom build steps depend on pre-generated files. If the build still fails after a clean rebuild, provide the plugin name or custom script that accesses .cache/graphql-schema.json, as that changes the recommendation.