GraphQL query resolving references on a _raw field in Gatsby

This is a known caching issue with Gatsby that affects reference resolution, particularly with complex reference chains like Mux video assets. While I don't have specific Sanity documentation about this exact scenario, I can share practical context and solutions.

What's Likely Happening

The gatsby-source-sanity plugin builds your Sanity content into Gatsby's internal GraphQL data layer. When you query _raw fields with resolveReferences, you're asking Gatsby to traverse reference chains (your document → mux.video → mux.asset).

When you reinstall node_modules, dependency versions or internal state can change, but Gatsby's cache still contains old data layer mappings. This mismatch can cause reference resolution to fail, returning null for nested fields like the Mux asset data. Running gatsby clean wipes this stale cache and forces a fresh rebuild where everything gets properly reconnected.

Practical Solutions

Make cache-clearing part of your reinstall workflow:

rm -rf node_modules
npm install
gatsby clean

Or create an npm script in your package.json:

{
  "scripts": {
    "reinstall": "rm -rf node_modules && npm install && gatsby clean"
  }
}

Ensure your GraphQL API is deployed:

The plugin needs a deployed GraphQL schema from Sanity. From your studio folder, run:

sanity graphql deploy

Keep gatsby-source-sanity updated:

npm install gatsby-source-sanity@latest

Newer versions may have improved cache handling.

Consider clearing cache more proactively:

If you're frequently switching branches or updating dependencies:

gatsby clean && gatsby develop

Why This Affects Development Only

The good news is this is typically a development-only issue. Production builds on services like Netlify or Gatsby Cloud start with clean caches by default, so your deployed site shouldn't experience this problem.

If Problems Persist

If you continue experiencing this after following the steps above, it would be worth reporting the specific behavior to the gatsby-source-sanity GitHub repository with details about your plugin version, Gatsby version, and configuration. The maintainers would have deeper insight into the plugin's caching mechanisms and could potentially address it in future versions.