Get help on Discord

Gatsby watchMode not refreshing on referenced document changes

71 replies
Last updated: Dec 1, 2025
Watch Mode does not refresh when a referenced document is updated in the CMS. Is this the expected behavior?
Stack is, React, Gatsby 3.x

This is schema from my ‘page’ document.

{
      name: "content",
      type: "array",
      title: "Page Sections",
      description: "Add, edit, and reorder sections",      
      of: [        
        {
          type: 'reference',
          to: [            
            { type: 'nav' },
            { type: 'section' },
            { type: 'footer' }
          ]
        }
      ],
    },
nav, section, and footer are all type ‘document’. for example…


export default {
  type: 'document',
  name: 'section',
  title: 'Page Sections',
  fields: [   
    {
      name: 'meta',
      title: 'Section Meta Data',
      type: 'meta'
    },
...
Gatsby Config is set properly


{
      resolve: `gatsby-source-sanity`,
      options: {
        projectId: `asdfasdf`,
        dataset: `template`,
        watchMode: true,
        overlayDrafts: true,        
        token: process.env.MY_SANITY_TOKEN,        
      },
    },
In the CMS / Studio, when you edit one of the fields, you can see Gatsby re-compile in dev mode from the terminal, however, the page does not auto reload. If I click the reload button or do a hard refresh in the browser, the changes do not render.

The only way to get it to render the changes is to go back to the CMS and edit a field on the main “Page” document. Then it refreshes immediately.

Any insight, even if it’s “Hey, this is the expected behavior” would be helpful.
AI Update

Based on the Sanity documentation I've reviewed, I cannot definitively confirm whether the behavior you're experiencing is expected or a bug. The gatsby-source-sanity documentation describes that watchMode enables real-time content preview by setting up a listener that pushes changes from Sanity to Gatsby, but it doesn't explicitly address how referenced documents should behave in this scenario.

What we know about gatsby-source-sanity:

The plugin is designed to be highly efficient, making only two API requests during the build process. When watchMode is enabled, it sets up a listener for real-time updates. However, the official documentation doesn't clarify whether changes to referenced documents should automatically trigger rebuilds of pages that reference them.

Your specific situation:

You're seeing Gatsby recompile when you edit a referenced document (visible in terminal), but the page doesn't reload with the changes until you edit the parent page document. This suggests the plugin is detecting the change but may not be triggering the full rebuild chain for documents that reference the changed content.

Potential approaches to investigate:

  1. Check your GraphQL queries: Make sure you're using _rawContent fields with resolveReferences when querying referenced documents:
query {
  sanityPage {
    _rawContent(resolveReferences: {maxDepth: 5})
  }
}

The _raw fields are specific to gatsby-source-sanity and designed to properly resolve references within your content.

  1. Verify your token permissions: Ensure your MY_SANITY_TOKEN has read permissions for all the document types (page, nav, section, footer).

  2. Check the gatsby-source-sanity GitHub issues: This might be a known issue or limitation with the plugin. I'd recommend searching the gatsby-source-sanity GitHub repository for similar issues or opening a new issue with your specific setup to get input from the maintainers.

  3. Temporary workaround: As you've discovered, editing the parent document triggers the refresh. You could add a "Last Modified" timestamp field to your page document and update it when needed during development.

Without access to verified information about this specific behavior in the plugin's issue tracker or detailed documentation, I can't confirm if this is expected behavior or a bug. I'd recommend reaching out to the Sanity community on their Slack community or opening a GitHub issue with this specific scenario to get a definitive answer from the plugin maintainers who can confirm the intended behavior.

Show original thread
71 replies

Sanity – Build the way you think, not the way your CMS thinks

Sanity is the developer-first content operating system that gives you complete control. Schema-as-code, GROQ queries, and real-time APIs mean no more workarounds or waiting for deployments. Free to start, scale as you grow.

Get started for freeExplore the demo

Was this answer helpful?