Is your Gatsby site rendering content? (Usually yes — with two catches)

Gatsby sits on the reassuring side of this set. Like Astro, its default output is real HTML — you are not fighting an empty shell the way you would with a plain React SPA. The interesting part of a Gatsby diagnosis is not "is the content there" but two subtler questions: was this specific page built yet, and does it survive rehydration in the browser.

Why a Gatsby build is safe by default

Running gatsby build executes your GraphQL queries, pulls the data they resolve, and writes a complete static HTML file for every page the build knows about. By the time the site is deployed, the content is already inside the HTML — there is no client-side assembly step for a crawler to wait on. That is why a healthy Gatsby page returns a content ratio at or near 100% with all metadata present before any JavaScript runs.

The mental model that trips people up: Gatsby is a build-time framework, not a request-time one. The HTML you serve was produced once, at build, not freshly on each request. Every Gatsby-specific issue below flows from that single fact.

The DSG first-request gap

Deferred Static Generation exists to shorten long builds. Marking a page with defer: true in createPages tells Gatsby not to build that page during gatsby build. Instead, the page is generated the first time someone requests it, then cached and served statically from then on. It is Gatsby's answer to sites with tens of thousands of pages where building all of them every time is impractical.

The SEO catch is the very first request. If Googlebot is the first visitor to a deferred page, it triggers the build and may receive a slow response — or, if your hosting mishandles the deferred path, an error or a shell — rather than the finished page. Once the page has been built once, it behaves like any other static page. So a DSG page that checks fine for you (because you already visited it) can still have been served an unbuilt version to the crawler that arrived first. Reserve DSG for genuinely low-priority pages, and keep anything you need indexed promptly in the normal build.

The rehydration blank-flash

This is the Gatsby failure that a green verdict can hide, so it is worth understanding precisely. Gatsby ships correct static HTML, then React rehydrates it in the browser to make it interactive. If the React tree the browser builds does not match the HTML Gatsby wrote at build time, React discards the server HTML and re-renders from scratch — which can flash a blank page, drop content, or scramble the layout.

The usual triggers are the same ones that break any React hydration: rendering new Date() or random values directly, branching on typeof window during render, or invalid HTML nesting that the browser silently corrects. In Gatsby these show up disproportionately because so much of the page is prebuilt — the gap between build output and browser render is exactly where they live.

Stale build-time data

Because GraphQL resolves at build time, the content in your HTML is a snapshot from your last build. Publish an article in your CMS, and it does not appear on the site — or in this checker — until a new build runs. This is not a rendering failure and the tool will not flag it as one, but it is the single most common reason a Gatsby page "isn't showing new content." If your content changes often, wire your CMS to trigger a rebuild on publish, or move the fast-changing pages to getServerData so they render per request.

Client-only routes are fine — if they shouldn't index

Gatsby supports client-only routes for app-like sections — a logged-in dashboard, an account area — using matchPath so a whole path prefix is handled by client-side routing. These sections are intentionally browser-rendered and will show as CSR in this check. That is correct and fine: dashboards should not be indexed. It only becomes a problem if something that should rank ended up behind a client-only route by accident. Check that your marketing and content pages are ordinary built pages, not swept into a client-only prefix.

Your configuration and the verdict to expect

Find your setup. On Gatsby, an unexpected amber or red almost always points to DSG, hydration, or a client-only route rather than to missing content.

When Gatsby actually breaks