Raw vs. Rendered HTML Checker

Free, no signup. Open the page in a browser and it looks complete; Google sees raw HTML first, then runs JavaScript and looks again — and those two views don't always agree. Test a public URL through the bounded rendering service to find where they diverge, with a side-by-side raw-vs-rendered diff.

Built by Patrick Stox

Free, no sign-up. The page is rendered in headless Chrome only when the initial HTML looks incomplete — most server-rendered sites never need it.

Checks run from our server; we fetch the URL you enter and don't keep the results. Reports are kept 7 days so you can share a link to the result. Anonymous aggregate stats feed our research posts; domains are counted once via an anonymized hash and never stored in the clear. Anonymous run-level outcome counters may be used for aggregate research; URLs, domains, IPs, and identifiers are never included, and no statistic is released below 100 runs.

Feedback
Report a bug

Found something broken in Render Gap? Let us know what happened — this goes straight to a private triage queue, not a public list.

What will be sent 
 No tool inputs, uploads, pasted source, complete results, query parameters, or URL fragments are attached automatically. You can edit or remove the selected passage above. Browser and anti-abuse metadata is processed for spam prevention. 
  
 
  
 
 
  
 
 
   
 
 
Sample report
 

Say you test a product page whose server response is essentially an empty container — the
          real content is painted in by a client-side framework. The initial HTML the tool fetches
          looks like this:

 
 
<div id="root"></div>
<script src="/assets/app.4f2c.js"></script>
 
 
…and the tool returns a verdict, a field comparison, and a flagged check:
 
Illustrative example — a live check renders the page in headless Chrome via this site's Browser Rendering binding, which this static page can't invoke; the verdict shape and thresholds shown match the real tool
 
 
 
 
 
Key content is missing until JavaScript runs
 
React · rendered in 4.2s · probed 0 expanders
 
 
 
 
 
 
Initial HTML what Googlebot reads first
 
Rendered DOM after JavaScript runs
 
 
 
Title
 
—
 
changedTrail Runner GTX — Waterproof Running Shoe
 
 
 
Words
 
12
 
1,840
 
 
 
Links
 
0
 
57
 
 
 
 
Error
Body content only appears after rendering
 
The initial HTML has 12 words; the rendered DOM has 1,840. Almost all of the page’s
              content and its 57 internal links depend on successful JavaScript rendering and are absent from the initial response.
 
 
 
     
  • The red verdict is the headline — nothing meaningful is in the server HTML at
            all, before JavaScript runs. See what each verdict color means
            ↓.
    •  
  • Title, words, and links all flip from empty to populated — the split table shows
            Googlebot's first read (12 words, 0 links) versus the rendered DOM (1,840 words, 57 links), which
            is the classic client-side-rendering render gap, not a partial one.
    •  
  • The fix is server-rendering, not just faster JavaScript — pre-rendering or SSR
            ships the title, copy, and links in the initial HTML so Google's first pass already sees them.
            More on this trade-off in JavaScript SEO.
    •  
 
 
 
How to use it
 
     
  1. Paste the full URL of the page you want to test into the box — the exact page,
            not just the homepage. A JavaScript-heavy template page is the most revealing.
    2.  
  2. Clear the anti-abuse check (Turnstile) and press Test page. The tool
            fetches the raw HTML first; if that looks like an empty shell, it renders the page in
            headless Chrome. Rendering, when it happens, takes roughly 10–20 seconds.
    3.  
  3. Read the coloured verdict at the top, then scan the
Initial HTML vs Rendered DOM table for rows flagged
changed — those are the fields JavaScript altered.
    4.  
  4. Open the individual checks below the table for the specific JS-SEO
            issues, grouped Problems → Worth fixing → Notes → Passing.
    5.  
  5. Switch to the Raw vs rendered diff tab to see line-by-line what
            JavaScript added or removed, and use Copy share link to save a report
            (kept 7 days).
    6.  
 
 
 
     
     
     
 
What this is checking
 
 
 
The render gap
 
Google can process JavaScript in a rendering phase after crawling. Content that appears only after rendering depends on that phase and is absent from the initial response; this comparison does not predict discovery or indexing timing.
 
 
 
The most restrictive rule wins
 
If a noindex appears in either the raw or rendered HTML, Google may use it — and an initial-HTML noindex may cause Google to skip rendering, so JavaScript cannot reliably undo it.
 
 
 
Canonicals are conditional
 
JavaScript may add a canonical when the raw HTML has none, or keep the same value. A different or additional value creates competing canonical input.
 
 
 

Checks based on the
JavaScript SEO guide
on Ahrefs. Confirm findings in
Search Console.

 
  
 
What the results mean
 
The verdict banner rolls the whole test into one of three levels:
 
     
  • Good (green) — the initial HTML already carries the important content
            and tags; JavaScript adds little or nothing that matters for indexing.
    •  
  • Warning (amber) — the page works but leans on rendering more than it
            should, e.g. some content or links only appear after JavaScript, or a tag differs between
            the two versions in a non-fatal way.
    •  
  • Problem (red) — something that can keep the page or its content out of
            search: an empty shell, a rendered-only noindex, a canonical conflict, or
            blocked resources.
    •  
 
Each individual check carries a severity badge:
 
     
  • Error — a real indexing risk to fix.
    •  
  • Warning — worth fixing; a fragility or inefficiency, not a hard block.
    •  
  • Information — a note or observation (framework detected, minor difference).
    •  
  • Pass — this aspect is healthy.
    •  
 

In the comparison table, a row tinted amber with a changed flag means that
          field—title, meta description, canonical, robots, word count, links, H1s, images without
          alt, structured-data blocks, or hreflang—is not the same in the initial HTML as in the
          rendered DOM.

 
How it works
 

A small Worker endpoint fetches your page’s raw HTML and its robots.txt.
          Only when that initial HTML looks incomplete does it render the page in headless
          Chrome (behind a cost ledger; a skipped render means the raw heuristic found substantial content, not that SSR or parity was proved).
          It returns both HTML versions to your browser.

 

Everything analytical then runs client-side. Each HTML version is parsed with an inert
DOMParser (scripts in the fetched HTML never execute), reduced to a snapshot of
          the fields that matter, and run through roughly fifteen calibrated JS-SEO checks. The tool
          detects the framework, builds the verdict, and produces the line-by-line raw-vs-rendered diff
          you see in the second tab. No sign-in, and reports are stored for seven days only for sharing.

 
Features
 
     
  • Side-by-side Initial HTML vs Rendered DOM table across ten fields, with
            every JavaScript-driven change flagged.
    •  
  • Around fifteen calibrated JS-SEO checks grouped by severity (Problems, Worth fixing,
            Notes, Passing), each with a plain-English summary and evidence.
    •  
  • A line-by-line raw-vs-rendered diff — green lines exist only after
            JavaScript runs; red lines were dropped from the rendered DOM.
    •  
  • Framework detection (React, Vue, Angular, and others) shown in the verdict meta line.
    •  
  • Renders in headless Chrome only when the raw-content heuristic requests it, and reports whether a render happened,
            was skipped without claiming SSR parity, or was unavailable.
    •  
  • Robots-aware: flags when robots.txt blocks the JavaScript or CSS Google needs
            to render the page.
    •  
  • Shareable reports kept for seven days; no sign-up, nothing stored beyond that.
    •  
 
Limitations
 

This is a fast, directional check — not Google’s renderer. Its headless Chrome is not
          the exact evergreen build Google uses, timing and network conditions differ, and it renders
          one page at a time. It will not click through complex interactions beyond probing common
          content expanders, and very large pages are truncated for analysis. When the initial HTML
          already looks complete, no render runs, so there is nothing to diff. For any finding that
          affects whether a URL is actually indexed, confirm it in Google Search Console’s URL
          Inspection tool, which runs Google’s own renderer on your verified property.

 
Frequently asked questions
 
What is the render gap in JavaScript SEO?
The render gap is the difference between what a page contains in its raw, server-delivered HTML and what it contains after the browser runs JavaScript and builds the final DOM. Google can process JavaScript in a rendering phase after crawling. Anything that appears only after JavaScript runs depends on successful rendering and is absent from the initial response. This tool measures that dependency; it does not predict when Google will discover or index the content.
Does Google actually render JavaScript?
Yes. Google renders pages with an evergreen Chromium, so client-side content can be indexed. Rendering is a separate processing phaseTurning HTML, CSS, and JavaScript into the final visual page and DOM., and blocked resources or JavaScript errors can prevent content from appearing in rendered HTML. Google Search does not interact with a page to load content, so content that requires an interaction must already be present in rendered HTML to be available. Putting critical content and tags in the server response removes that rendering dependency.
Why does this tool sometimes not render my page?
Headless Chrome runs only when a bounded heuristic says the initial HTML looks incomplete. Substantial raw titles, links, and body text can make the tool skip rendering, but that does not prove the framework is server-rendered or that JavaScript would add nothing. A skipped run gives an initial-HTML analysis without a rendered parity comparison.
Is a JavaScript-inserted canonical or noindex respected by Google?
Google may skip rendering after it sees noindexNoindex is a directive that tells search engines to keep a page out of their index, so it won't appear in search results. It works only on pages a crawler can actually fetch — a page blocked in robots.txt can never be noindexed. in the initial HTML, so JavaScript cannot reliably remove that directive later; rendered-only noindex can also be used. For canonicals, JavaScript may add one when the initial HTML has none, and setting the same value is okay. Changing it to a different value or leaving multiple values creates risky competing input.
Is this the same as Google Search Console’s URL Inspection tool?
No, and it is not meant to replace it. This is a fast, directional comparison. Search Console’s URL Inspection toolA Google Search Console feature that reports how Google sees one specific URL on a property you own. By default it shows the last-indexed snapshot; a separate "Test live URL" mode fetches the current version. provides Google-specific crawl, indexingStoring a crawled page in the search index so it can appear in results. Crawled is not the same as indexed — Google selects what to keep, and indexing isn't guaranteed., and live-test evidence for a verified property, but neither tool guarantees how a URL will be processed on a later crawl.
 
 
 
        
Next stepXML Sitemap Generator — generate the corrected version.

Explore more
ToolSEO Incident SimulatorToolGoogle Index CheckerToolCanonicalization CheckerArticleJavaScript SEOArticlePage Indexed Without ContentArticleTechnical SEO
 
 
 
Feature requests for Render Gap
 

Upvote what you want most. New ideas can be submitted from the floating Feedback menu;
      requests appear here once approved, and the most-wanted rise to the top.

   
Loading…
  
  ➕ Request a feature   
New requests are reviewed before they appear here.
 
     
  
  
 
 
 
 
          
 
Common issues & how to fix them
 
 
 
 
 
Raw vs. Rendered HTML Checker · one finding
 
JavaScript removes noindex
 
Recommended action: Remove noindex from the initial server response when the page should be indexed; do not rely on JavaScript to undo it.
 
Fix principle: Remove every unintended noindex from its confirmed owner; absence of noindex is sufficient, while an explicit index directive cannot override another noindex because restrictive directives combine.
 
 
 
 Implementation for your setup 
 
Confirm first: The final HTML or HTTP response contains a noindex directive, including one added only by client-side script during rendering. The page is intended to be an indexable canonical URL. A robots meta tag or X-Robots-Tag intended to keep the page indexable is neutralized by a conflicting directive elsewhere, because directives combine using the most restrictive rule. Robots.txt disallows the URL itself, or disallows a resource the page depends on to render, so the crawler cannot reach or fully evaluate the intended indexable page.
 
Do not apply when: Exclusion is intentional for the page type, environment, or workflow state. The directive appears only on a noncanonical or otherwise ineligible URL. Robots.txt does not disallow the URL or the resources it needs to render, and the effective combination of every directive already resolves to the intended indexable state.
 
Likely control points: cms-app · server · edge-cdn
 
   
Choose the layer that owns the final response.
 
 
 
Generic HTTP / HTML
 
Status: supported · Location: The application, server, or edge owner that emits the directive, or the robots.txt file at the site root
 
Steps
  1. Follow redirects, identify the exact owner of each unintended robots/googlebot meta or X-Robots-Tag noindex, and remove it only at that owner.
  2. Return the intended canonical page with a crawlable 200 response, align its canonical, and purge the caches that can retain the directive.
  3. If a robots meta tag or X-Robots-Tag is present but rendered ineffective by a conflicting directive elsewhere, remove the actual unwanted restrictive directive rather than adding a permissive one to compete with it — the most restrictive rule always wins. Google also honors a robots meta tag placed outside <head>, so an out-of-head placement is a specification and cross-crawler risk to correct, not by itself proof Google is ignoring the directive.
  4. If robots.txt disallows the URL itself, or disallows a resource (such as CSS or JS) the page needs to render its content, correct only the specific Disallow rule at the robots.txt file that owns it — keep the rule as narrow as its original intent, and remember Disallow blocks crawling, not indexing: a disallowed URL can still be indexed if discovered elsewhere.
  5. Keep the URL crawlable so Google can observe the removal.
  
Verify on this platform
 
  • After redirects and cache purge, inspect every robots and googlebot meta tag plus every X-Robots-Tag value on the final response.
  • Fetch and parse robots.txt for every group that applies to the relevant user-agent — Google consolidates every group matching the same user-agent token into one effective ruleset, though not every crawler does — and confirm the URL and its critical rendering resources are not disallowed.
  • Use Search Console URL Inspection’s live test on the production URL, then request indexing when appropriate.
 
Rollback
  1. Restore the prior directive or robots.txt rule if the page or a resource it needs was exposed or blocked unintentionally, then correct the underlying publication rule before trying again.
 
Caveats
  • Do not add index as a counter-directive: the most restrictive directive applies, so another noindex still wins.
  • The live test checks current accessibility; it does not guarantee selection, canonical choice, or indexing.
  • Google’s own parser combines every robots.txt group matching the same user-agent token into one effective ruleset, but many other crawlers and Robots Exclusion Protocol implementations honor only the first matching group — treat a directive split across groups as a real interoperability risk even when Google itself is unaffected.
  • If the page combines a canonical to a different URL with a noindex directive, remove the noindex only if this URL itself should be indexable; if the canonical target is the one meant to be indexed, keep the noindex here and verify the canonical target separately rather than treating its indexability as confirmed by removing this noindex.
 
Official sources
 
 
WordPress
 
Status: supported · Location: Global Settings → Reading/blog_public, or the scoped plugin/theme callback that owns wp_robots
 
Steps
  1. If WordPress core globally owns the directive, confirm the scope and change Settings → Reading so blog_public permits search-engine visibility.
  2. For a scoped page-type or URL rule, identify and change the plugin or theme callback filtering wp_robots or invoking the core noindex behavior; do not invent a plugin UI.
  3. Purge page, object, host, and edge caches that can retain the old output.
  
Verify on this platform
 
  • While logged out, follow redirects and inspect all robots/googlebot meta plus X-Robots-Tag values on the final public response.
 
Rollback
  1. Restore the previous visibility or plugin setting if unintended pages become indexable.
 
Caveats
  • Do not use the global Reading setting to solve a scoped plugin or theme rule.
  • WordPress exposes the wp_robots API, but a third-party owner’s exact UI is not verified here.
  • Robots.txt is a separate control point from this meta/header directive — correct a Disallow rule using the generic-http-html guidance above regardless of which CMS serves the site.
 
Official sources
 
 
Cloudflare Workers / Rules
 
Status: supported · Location: Confirmed Response Header Transform Rule or Worker emitter
 
Steps
  1. Use Cloudflare Trace and configuration review to confirm which Transform Rule or Worker adds the final X-Robots-Tag and account for response-header rule ordering.
  2. Narrow or remove only that confirmed edge emitter; in a Worker, clone the response before modifying its headers.
  3. Purge the affected cache entries and leave any valid origin-owned robots header intact.
  
Verify on this platform
 
  • Compare origin and final Cloudflare responses after redirects, then confirm every final robots header and meta directive is free of unintended noindex.
 
Rollback
  1. Restore the prior edge rule if the scope change exposes excluded routes, then replace it with a narrower condition.
 
Caveats
  • Never blanket-delete a valid origin X-Robots-Tag when Cloudflare is not the confirmed emitter.
  • Later response-header rules can override earlier changes, so verify the final rule order and response.
  • Robots.txt is a separate control point from this response-header directive — correct a Disallow rule using the generic-http-html guidance above.
 
Official sources
 
 
Next.js / Vercel
 
Status: supported · Location: App Router metadata/generateMetadata, Pages Router next/head, or next.config headers()
 
Steps
  1. In the App Router, remove the unintended noindex from static metadata.robots or generateMetadata at the route that owns it.
  2. In the Pages Router, correct the owning next/head robots meta; for an X-Robots-Tag, correct the scoped next.config headers() rule.
  3. Deploy to the intended production environment and purge or bypass relevant caches before verification.
  
Verify on this platform
 
  • Inspect all final robots/googlebot meta and X-Robots-Tag values after redirects on the current production deployment.
 
Rollback
  1. Revert the route metadata, Head output, or headers() rule if the deployment exposes a route that should remain excluded.
 
Caveats
  • Vercel intentionally serves X-Robots-Tag: noindex for Preview Deployments and outdated Production Deployments; preserve that protection.
  • Do not diagnose an intentional preview response as a production metadata defect.
  • Robots.txt (a static file or a route handler such as app/robots.ts) is a separate control point from this metadata/header directive — correct a Disallow rule using the generic-http-html guidance above.
 
Official sources
 
 
Platform-managed / ask the vendor
 
Status: platform-managed · Location: Vendor-owned publication, visibility, or response-header control
 
Steps
  1. Ask the vendor to identify the exact global or scoped control that emits noindex and remove it only for the confirmed public canonical URL.
  
Verify on this platform
 
  • Follow redirects and inspect all robots/googlebot meta and X-Robots-Tag values on the final public response, then use the Search Console live test.
 
Rollback
  1. Restore the vendor visibility control if an unintended page becomes public while the owning rule is corrected.
 
Caveats
  • Do not add index to compete with a noindex emitted elsewhere.
  • Keep the URL crawlable long enough for search engines to observe the removal.
  • Ask the vendor to confirm whether it also owns robots.txt for the domain — a Disallow rule there is a separate control point from a meta/header directive.
 
Official sources
 
 
 
 
 How to verify 
 
  1. Follow redirects and confirm a crawlable 200 final response with no noindex in any robots/googlebot meta or X-Robots-Tag value.
  2. Confirm the canonical points to the intended URL and relevant caches no longer serve the directive.
  3. Fetch and parse robots.txt for the applicable user-agent group(s) and confirm the URL and its critical rendering resources are not disallowed.
  4. Rerun SEO Site Audit Crawler, On-Page SEO Checker, Google Index Checker, Render Gap, or Robots.txt Tester (whichever surfaced the finding), and use Search Console URL Inspection’s live test for Google’s current view.
 
Escalate when
 
Escalate when page ownership or publication intent is unclear, noindex or a robots.txt Disallow rule is applied by multiple layers, or removing it would expose private, duplicate, or staging content.
 
 
 
 
 
 
 
Raw vs. Rendered HTML Checker · one finding
 
JavaScript adds noindex
 
Recommended action: Stop client code from adding noindex to pages that should remain indexable.
 
Fix principle: Remove every unintended noindex from its confirmed owner; absence of noindex is sufficient, while an explicit index directive cannot override another noindex because restrictive directives combine.
 
 
 
 Implementation for your setup 
 
Confirm first: The final HTML or HTTP response contains a noindex directive, including one added only by client-side script during rendering. The page is intended to be an indexable canonical URL. A robots meta tag or X-Robots-Tag intended to keep the page indexable is neutralized by a conflicting directive elsewhere, because directives combine using the most restrictive rule. Robots.txt disallows the URL itself, or disallows a resource the page depends on to render, so the crawler cannot reach or fully evaluate the intended indexable page.
 
Do not apply when: Exclusion is intentional for the page type, environment, or workflow state. The directive appears only on a noncanonical or otherwise ineligible URL. Robots.txt does not disallow the URL or the resources it needs to render, and the effective combination of every directive already resolves to the intended indexable state.
 
Likely control points: cms-app · server · edge-cdn
 
   
Choose the layer that owns the final response.
 
 
 
Generic HTTP / HTML
 
Status: supported · Location: The application, server, or edge owner that emits the directive, or the robots.txt file at the site root
 
Steps
  1. Follow redirects, identify the exact owner of each unintended robots/googlebot meta or X-Robots-Tag noindex, and remove it only at that owner.
  2. Return the intended canonical page with a crawlable 200 response, align its canonical, and purge the caches that can retain the directive.
  3. If a robots meta tag or X-Robots-Tag is present but rendered ineffective by a conflicting directive elsewhere, remove the actual unwanted restrictive directive rather than adding a permissive one to compete with it — the most restrictive rule always wins. Google also honors a robots meta tag placed outside <head>, so an out-of-head placement is a specification and cross-crawler risk to correct, not by itself proof Google is ignoring the directive.
  4. If robots.txt disallows the URL itself, or disallows a resource (such as CSS or JS) the page needs to render its content, correct only the specific Disallow rule at the robots.txt file that owns it — keep the rule as narrow as its original intent, and remember Disallow blocks crawling, not indexing: a disallowed URL can still be indexed if discovered elsewhere.
  5. Keep the URL crawlable so Google can observe the removal.
  
Verify on this platform
 
  • After redirects and cache purge, inspect every robots and googlebot meta tag plus every X-Robots-Tag value on the final response.
  • Fetch and parse robots.txt for every group that applies to the relevant user-agent — Google consolidates every group matching the same user-agent token into one effective ruleset, though not every crawler does — and confirm the URL and its critical rendering resources are not disallowed.
  • Use Search Console URL Inspection’s live test on the production URL, then request indexing when appropriate.
 
Rollback
  1. Restore the prior directive or robots.txt rule if the page or a resource it needs was exposed or blocked unintentionally, then correct the underlying publication rule before trying again.
 
Caveats
  • Do not add index as a counter-directive: the most restrictive directive applies, so another noindex still wins.
  • The live test checks current accessibility; it does not guarantee selection, canonical choice, or indexing.
  • Google’s own parser combines every robots.txt group matching the same user-agent token into one effective ruleset, but many other crawlers and Robots Exclusion Protocol implementations honor only the first matching group — treat a directive split across groups as a real interoperability risk even when Google itself is unaffected.
  • If the page combines a canonical to a different URL with a noindex directive, remove the noindex only if this URL itself should be indexable; if the canonical target is the one meant to be indexed, keep the noindex here and verify the canonical target separately rather than treating its indexability as confirmed by removing this noindex.
 
Official sources
 
 
WordPress
 
Status: supported · Location: Global Settings → Reading/blog_public, or the scoped plugin/theme callback that owns wp_robots
 
Steps
  1. If WordPress core globally owns the directive, confirm the scope and change Settings → Reading so blog_public permits search-engine visibility.
  2. For a scoped page-type or URL rule, identify and change the plugin or theme callback filtering wp_robots or invoking the core noindex behavior; do not invent a plugin UI.
  3. Purge page, object, host, and edge caches that can retain the old output.
  
Verify on this platform
 
  • While logged out, follow redirects and inspect all robots/googlebot meta plus X-Robots-Tag values on the final public response.
 
Rollback
  1. Restore the previous visibility or plugin setting if unintended pages become indexable.
 
Caveats
  • Do not use the global Reading setting to solve a scoped plugin or theme rule.
  • WordPress exposes the wp_robots API, but a third-party owner’s exact UI is not verified here.
  • Robots.txt is a separate control point from this meta/header directive — correct a Disallow rule using the generic-http-html guidance above regardless of which CMS serves the site.
 
Official sources
 
 
Cloudflare Workers / Rules
 
Status: supported · Location: Confirmed Response Header Transform Rule or Worker emitter
 
Steps
  1. Use Cloudflare Trace and configuration review to confirm which Transform Rule or Worker adds the final X-Robots-Tag and account for response-header rule ordering.
  2. Narrow or remove only that confirmed edge emitter; in a Worker, clone the response before modifying its headers.
  3. Purge the affected cache entries and leave any valid origin-owned robots header intact.
  
Verify on this platform
 
  • Compare origin and final Cloudflare responses after redirects, then confirm every final robots header and meta directive is free of unintended noindex.
 
Rollback
  1. Restore the prior edge rule if the scope change exposes excluded routes, then replace it with a narrower condition.
 
Caveats
  • Never blanket-delete a valid origin X-Robots-Tag when Cloudflare is not the confirmed emitter.
  • Later response-header rules can override earlier changes, so verify the final rule order and response.
  • Robots.txt is a separate control point from this response-header directive — correct a Disallow rule using the generic-http-html guidance above.
 
Official sources
 
 
Next.js / Vercel
 
Status: supported · Location: App Router metadata/generateMetadata, Pages Router next/head, or next.config headers()
 
Steps
  1. In the App Router, remove the unintended noindex from static metadata.robots or generateMetadata at the route that owns it.
  2. In the Pages Router, correct the owning next/head robots meta; for an X-Robots-Tag, correct the scoped next.config headers() rule.
  3. Deploy to the intended production environment and purge or bypass relevant caches before verification.
  
Verify on this platform
 
  • Inspect all final robots/googlebot meta and X-Robots-Tag values after redirects on the current production deployment.
 
Rollback
  1. Revert the route metadata, Head output, or headers() rule if the deployment exposes a route that should remain excluded.
 
Caveats
  • Vercel intentionally serves X-Robots-Tag: noindex for Preview Deployments and outdated Production Deployments; preserve that protection.
  • Do not diagnose an intentional preview response as a production metadata defect.
  • Robots.txt (a static file or a route handler such as app/robots.ts) is a separate control point from this metadata/header directive — correct a Disallow rule using the generic-http-html guidance above.
 
Official sources
 
 
Platform-managed / ask the vendor
 
Status: platform-managed · Location: Vendor-owned publication, visibility, or response-header control
 
Steps
  1. Ask the vendor to identify the exact global or scoped control that emits noindex and remove it only for the confirmed public canonical URL.
  
Verify on this platform
 
  • Follow redirects and inspect all robots/googlebot meta and X-Robots-Tag values on the final public response, then use the Search Console live test.
 
Rollback
  1. Restore the vendor visibility control if an unintended page becomes public while the owning rule is corrected.
 
Caveats
  • Do not add index to compete with a noindex emitted elsewhere.
  • Keep the URL crawlable long enough for search engines to observe the removal.
  • Ask the vendor to confirm whether it also owns robots.txt for the domain — a Disallow rule there is a separate control point from a meta/header directive.
 
Official sources
 
 
 
 
 How to verify 
 
  1. Follow redirects and confirm a crawlable 200 final response with no noindex in any robots/googlebot meta or X-Robots-Tag value.
  2. Confirm the canonical points to the intended URL and relevant caches no longer serve the directive.
  3. Fetch and parse robots.txt for the applicable user-agent group(s) and confirm the URL and its critical rendering resources are not disallowed.
  4. Rerun SEO Site Audit Crawler, On-Page SEO Checker, Google Index Checker, Render Gap, or Robots.txt Tester (whichever surfaced the finding), and use Search Console URL Inspection’s live test for Google’s current view.
 
Escalate when
 
Escalate when page ownership or publication intent is unclear, noindex or a robots.txt Disallow rule is applied by multiple layers, or removing it would expose private, duplicate, or staging content.
 
 
 
 
 
 
 
Raw vs. Rendered HTML Checker · one finding
 
Noindex remains after rendering
 
Recommended action: Remove the noindex directive from both initial and rendered HTML when the page should be indexed.
 
Fix principle: Remove every unintended noindex from its confirmed owner; absence of noindex is sufficient, while an explicit index directive cannot override another noindex because restrictive directives combine.
 
 
 
 Implementation for your setup 
 
Confirm first: The final HTML or HTTP response contains a noindex directive, including one added only by client-side script during rendering. The page is intended to be an indexable canonical URL. A robots meta tag or X-Robots-Tag intended to keep the page indexable is neutralized by a conflicting directive elsewhere, because directives combine using the most restrictive rule. Robots.txt disallows the URL itself, or disallows a resource the page depends on to render, so the crawler cannot reach or fully evaluate the intended indexable page.
 
Do not apply when: Exclusion is intentional for the page type, environment, or workflow state. The directive appears only on a noncanonical or otherwise ineligible URL. Robots.txt does not disallow the URL or the resources it needs to render, and the effective combination of every directive already resolves to the intended indexable state.
 
Likely control points: cms-app · server · edge-cdn
 
   
Choose the layer that owns the final response.
 
 
 
Generic HTTP / HTML
 
Status: supported · Location: The application, server, or edge owner that emits the directive, or the robots.txt file at the site root
 
Steps
  1. Follow redirects, identify the exact owner of each unintended robots/googlebot meta or X-Robots-Tag noindex, and remove it only at that owner.
  2. Return the intended canonical page with a crawlable 200 response, align its canonical, and purge the caches that can retain the directive.
  3. If a robots meta tag or X-Robots-Tag is present but rendered ineffective by a conflicting directive elsewhere, remove the actual unwanted restrictive directive rather than adding a permissive one to compete with it — the most restrictive rule always wins. Google also honors a robots meta tag placed outside <head>, so an out-of-head placement is a specification and cross-crawler risk to correct, not by itself proof Google is ignoring the directive.
  4. If robots.txt disallows the URL itself, or disallows a resource (such as CSS or JS) the page needs to render its content, correct only the specific Disallow rule at the robots.txt file that owns it — keep the rule as narrow as its original intent, and remember Disallow blocks crawling, not indexing: a disallowed URL can still be indexed if discovered elsewhere.
  5. Keep the URL crawlable so Google can observe the removal.
  
Verify on this platform
 
  • After redirects and cache purge, inspect every robots and googlebot meta tag plus every X-Robots-Tag value on the final response.
  • Fetch and parse robots.txt for every group that applies to the relevant user-agent — Google consolidates every group matching the same user-agent token into one effective ruleset, though not every crawler does — and confirm the URL and its critical rendering resources are not disallowed.
  • Use Search Console URL Inspection’s live test on the production URL, then request indexing when appropriate.
 
Rollback
  1. Restore the prior directive or robots.txt rule if the page or a resource it needs was exposed or blocked unintentionally, then correct the underlying publication rule before trying again.
 
Caveats
  • Do not add index as a counter-directive: the most restrictive directive applies, so another noindex still wins.
  • The live test checks current accessibility; it does not guarantee selection, canonical choice, or indexing.
  • Google’s own parser combines every robots.txt group matching the same user-agent token into one effective ruleset, but many other crawlers and Robots Exclusion Protocol implementations honor only the first matching group — treat a directive split across groups as a real interoperability risk even when Google itself is unaffected.
  • If the page combines a canonical to a different URL with a noindex directive, remove the noindex only if this URL itself should be indexable; if the canonical target is the one meant to be indexed, keep the noindex here and verify the canonical target separately rather than treating its indexability as confirmed by removing this noindex.
 
Official sources
 
 
WordPress
 
Status: supported · Location: Global Settings → Reading/blog_public, or the scoped plugin/theme callback that owns wp_robots
 
Steps
  1. If WordPress core globally owns the directive, confirm the scope and change Settings → Reading so blog_public permits search-engine visibility.
  2. For a scoped page-type or URL rule, identify and change the plugin or theme callback filtering wp_robots or invoking the core noindex behavior; do not invent a plugin UI.
  3. Purge page, object, host, and edge caches that can retain the old output.
  
Verify on this platform
 
  • While logged out, follow redirects and inspect all robots/googlebot meta plus X-Robots-Tag values on the final public response.
 
Rollback
  1. Restore the previous visibility or plugin setting if unintended pages become indexable.
 
Caveats
  • Do not use the global Reading setting to solve a scoped plugin or theme rule.
  • WordPress exposes the wp_robots API, but a third-party owner’s exact UI is not verified here.
  • Robots.txt is a separate control point from this meta/header directive — correct a Disallow rule using the generic-http-html guidance above regardless of which CMS serves the site.
 
Official sources
 
 
Cloudflare Workers / Rules
 
Status: supported · Location: Confirmed Response Header Transform Rule or Worker emitter
 
Steps
  1. Use Cloudflare Trace and configuration review to confirm which Transform Rule or Worker adds the final X-Robots-Tag and account for response-header rule ordering.
  2. Narrow or remove only that confirmed edge emitter; in a Worker, clone the response before modifying its headers.
  3. Purge the affected cache entries and leave any valid origin-owned robots header intact.
  
Verify on this platform
 
  • Compare origin and final Cloudflare responses after redirects, then confirm every final robots header and meta directive is free of unintended noindex.
 
Rollback
  1. Restore the prior edge rule if the scope change exposes excluded routes, then replace it with a narrower condition.
 
Caveats
  • Never blanket-delete a valid origin X-Robots-Tag when Cloudflare is not the confirmed emitter.
  • Later response-header rules can override earlier changes, so verify the final rule order and response.
  • Robots.txt is a separate control point from this response-header directive — correct a Disallow rule using the generic-http-html guidance above.
 
Official sources
 
 
Next.js / Vercel
 
Status: supported · Location: App Router metadata/generateMetadata, Pages Router next/head, or next.config headers()
 
Steps
  1. In the App Router, remove the unintended noindex from static metadata.robots or generateMetadata at the route that owns it.
  2. In the Pages Router, correct the owning next/head robots meta; for an X-Robots-Tag, correct the scoped next.config headers() rule.
  3. Deploy to the intended production environment and purge or bypass relevant caches before verification.
  
Verify on this platform
 
  • Inspect all final robots/googlebot meta and X-Robots-Tag values after redirects on the current production deployment.
 
Rollback
  1. Revert the route metadata, Head output, or headers() rule if the deployment exposes a route that should remain excluded.
 
Caveats
  • Vercel intentionally serves X-Robots-Tag: noindex for Preview Deployments and outdated Production Deployments; preserve that protection.
  • Do not diagnose an intentional preview response as a production metadata defect.
  • Robots.txt (a static file or a route handler such as app/robots.ts) is a separate control point from this metadata/header directive — correct a Disallow rule using the generic-http-html guidance above.
 
Official sources
 
 
Platform-managed / ask the vendor
 
Status: platform-managed · Location: Vendor-owned publication, visibility, or response-header control
 
Steps
  1. Ask the vendor to identify the exact global or scoped control that emits noindex and remove it only for the confirmed public canonical URL.
  
Verify on this platform
 
  • Follow redirects and inspect all robots/googlebot meta and X-Robots-Tag values on the final public response, then use the Search Console live test.
 
Rollback
  1. Restore the vendor visibility control if an unintended page becomes public while the owning rule is corrected.
 
Caveats
  • Do not add index to compete with a noindex emitted elsewhere.
  • Keep the URL crawlable long enough for search engines to observe the removal.
  • Ask the vendor to confirm whether it also owns robots.txt for the domain — a Disallow rule there is a separate control point from a meta/header directive.
 
Official sources
 
 
 
 
 How to verify 
 
  1. Follow redirects and confirm a crawlable 200 final response with no noindex in any robots/googlebot meta or X-Robots-Tag value.
  2. Confirm the canonical points to the intended URL and relevant caches no longer serve the directive.
  3. Fetch and parse robots.txt for the applicable user-agent group(s) and confirm the URL and its critical rendering resources are not disallowed.
  4. Rerun SEO Site Audit Crawler, On-Page SEO Checker, Google Index Checker, Render Gap, or Robots.txt Tester (whichever surfaced the finding), and use Search Console URL Inspection’s live test for Google’s current view.
 
Escalate when
 
Escalate when page ownership or publication intent is unclear, noindex or a robots.txt Disallow rule is applied by multiple layers, or removing it would expose private, duplicate, or staging content.
 
 
 
 
 
 
 
Raw vs. Rendered HTML Checker · one finding
 
Nofollow remains after rendering
 
Recommended action: Remove nofollow when crawlers should follow the page’s links, or scope it only to links that require it.
 
Fix principle: Remove every unintended noindex from its confirmed owner; absence of noindex is sufficient, while an explicit index directive cannot override another noindex because restrictive directives combine.
 
 
 
 Implementation for your setup 
 
Confirm first: The final HTML or HTTP response contains a noindex directive, including one added only by client-side script during rendering. The page is intended to be an indexable canonical URL. A robots meta tag or X-Robots-Tag intended to keep the page indexable is neutralized by a conflicting directive elsewhere, because directives combine using the most restrictive rule. Robots.txt disallows the URL itself, or disallows a resource the page depends on to render, so the crawler cannot reach or fully evaluate the intended indexable page.
 
Do not apply when: Exclusion is intentional for the page type, environment, or workflow state. The directive appears only on a noncanonical or otherwise ineligible URL. Robots.txt does not disallow the URL or the resources it needs to render, and the effective combination of every directive already resolves to the intended indexable state.
 
Likely control points: cms-app · server · edge-cdn
 
   
Choose the layer that owns the final response.
 
 
 
Generic HTTP / HTML
 
Status: supported · Location: The application, server, or edge owner that emits the directive, or the robots.txt file at the site root
 
Steps
  1. Follow redirects, identify the exact owner of each unintended robots/googlebot meta or X-Robots-Tag noindex, and remove it only at that owner.
  2. Return the intended canonical page with a crawlable 200 response, align its canonical, and purge the caches that can retain the directive.
  3. If a robots meta tag or X-Robots-Tag is present but rendered ineffective by a conflicting directive elsewhere, remove the actual unwanted restrictive directive rather than adding a permissive one to compete with it — the most restrictive rule always wins. Google also honors a robots meta tag placed outside <head>, so an out-of-head placement is a specification and cross-crawler risk to correct, not by itself proof Google is ignoring the directive.
  4. If robots.txt disallows the URL itself, or disallows a resource (such as CSS or JS) the page needs to render its content, correct only the specific Disallow rule at the robots.txt file that owns it — keep the rule as narrow as its original intent, and remember Disallow blocks crawling, not indexing: a disallowed URL can still be indexed if discovered elsewhere.
  5. Keep the URL crawlable so Google can observe the removal.
  
Verify on this platform
 
  • After redirects and cache purge, inspect every robots and googlebot meta tag plus every X-Robots-Tag value on the final response.
  • Fetch and parse robots.txt for every group that applies to the relevant user-agent — Google consolidates every group matching the same user-agent token into one effective ruleset, though not every crawler does — and confirm the URL and its critical rendering resources are not disallowed.
  • Use Search Console URL Inspection’s live test on the production URL, then request indexing when appropriate.
 
Rollback
  1. Restore the prior directive or robots.txt rule if the page or a resource it needs was exposed or blocked unintentionally, then correct the underlying publication rule before trying again.
 
Caveats
  • Do not add index as a counter-directive: the most restrictive directive applies, so another noindex still wins.
  • The live test checks current accessibility; it does not guarantee selection, canonical choice, or indexing.
  • Google’s own parser combines every robots.txt group matching the same user-agent token into one effective ruleset, but many other crawlers and Robots Exclusion Protocol implementations honor only the first matching group — treat a directive split across groups as a real interoperability risk even when Google itself is unaffected.
  • If the page combines a canonical to a different URL with a noindex directive, remove the noindex only if this URL itself should be indexable; if the canonical target is the one meant to be indexed, keep the noindex here and verify the canonical target separately rather than treating its indexability as confirmed by removing this noindex.
 
Official sources
 
 
WordPress
 
Status: supported · Location: Global Settings → Reading/blog_public, or the scoped plugin/theme callback that owns wp_robots
 
Steps
  1. If WordPress core globally owns the directive, confirm the scope and change Settings → Reading so blog_public permits search-engine visibility.
  2. For a scoped page-type or URL rule, identify and change the plugin or theme callback filtering wp_robots or invoking the core noindex behavior; do not invent a plugin UI.
  3. Purge page, object, host, and edge caches that can retain the old output.
  
Verify on this platform
 
  • While logged out, follow redirects and inspect all robots/googlebot meta plus X-Robots-Tag values on the final public response.
 
Rollback
  1. Restore the previous visibility or plugin setting if unintended pages become indexable.
 
Caveats
  • Do not use the global Reading setting to solve a scoped plugin or theme rule.
  • WordPress exposes the wp_robots API, but a third-party owner’s exact UI is not verified here.
  • Robots.txt is a separate control point from this meta/header directive — correct a Disallow rule using the generic-http-html guidance above regardless of which CMS serves the site.
 
Official sources
 
 
Cloudflare Workers / Rules
 
Status: supported · Location: Confirmed Response Header Transform Rule or Worker emitter
 
Steps
  1. Use Cloudflare Trace and configuration review to confirm which Transform Rule or Worker adds the final X-Robots-Tag and account for response-header rule ordering.
  2. Narrow or remove only that confirmed edge emitter; in a Worker, clone the response before modifying its headers.
  3. Purge the affected cache entries and leave any valid origin-owned robots header intact.
  
Verify on this platform
 
  • Compare origin and final Cloudflare responses after redirects, then confirm every final robots header and meta directive is free of unintended noindex.
 
Rollback
  1. Restore the prior edge rule if the scope change exposes excluded routes, then replace it with a narrower condition.
 
Caveats
  • Never blanket-delete a valid origin X-Robots-Tag when Cloudflare is not the confirmed emitter.
  • Later response-header rules can override earlier changes, so verify the final rule order and response.
  • Robots.txt is a separate control point from this response-header directive — correct a Disallow rule using the generic-http-html guidance above.
 
Official sources
 
 
Next.js / Vercel
 
Status: supported · Location: App Router metadata/generateMetadata, Pages Router next/head, or next.config headers()
 
Steps
  1. In the App Router, remove the unintended noindex from static metadata.robots or generateMetadata at the route that owns it.
  2. In the Pages Router, correct the owning next/head robots meta; for an X-Robots-Tag, correct the scoped next.config headers() rule.
  3. Deploy to the intended production environment and purge or bypass relevant caches before verification.
  
Verify on this platform
 
  • Inspect all final robots/googlebot meta and X-Robots-Tag values after redirects on the current production deployment.
 
Rollback
  1. Revert the route metadata, Head output, or headers() rule if the deployment exposes a route that should remain excluded.
 
Caveats
  • Vercel intentionally serves X-Robots-Tag: noindex for Preview Deployments and outdated Production Deployments; preserve that protection.
  • Do not diagnose an intentional preview response as a production metadata defect.
  • Robots.txt (a static file or a route handler such as app/robots.ts) is a separate control point from this metadata/header directive — correct a Disallow rule using the generic-http-html guidance above.
 
Official sources
 
 
Platform-managed / ask the vendor
 
Status: platform-managed · Location: Vendor-owned publication, visibility, or response-header control
 
Steps
  1. Ask the vendor to identify the exact global or scoped control that emits noindex and remove it only for the confirmed public canonical URL.
  
Verify on this platform
 
  • Follow redirects and inspect all robots/googlebot meta and X-Robots-Tag values on the final public response, then use the Search Console live test.
 
Rollback
  1. Restore the vendor visibility control if an unintended page becomes public while the owning rule is corrected.
 
Caveats
  • Do not add index to compete with a noindex emitted elsewhere.
  • Keep the URL crawlable long enough for search engines to observe the removal.
  • Ask the vendor to confirm whether it also owns robots.txt for the domain — a Disallow rule there is a separate control point from a meta/header directive.
 
Official sources
 
 
 
 
 How to verify 
 
  1. Follow redirects and confirm a crawlable 200 final response with no noindex in any robots/googlebot meta or X-Robots-Tag value.
  2. Confirm the canonical points to the intended URL and relevant caches no longer serve the directive.
  3. Fetch and parse robots.txt for the applicable user-agent group(s) and confirm the URL and its critical rendering resources are not disallowed.
  4. Rerun SEO Site Audit Crawler, On-Page SEO Checker, Google Index Checker, Render Gap, or Robots.txt Tester (whichever surfaced the finding), and use Search Console URL Inspection’s live test for Google’s current view.
 
Escalate when
 
Escalate when page ownership or publication intent is unclear, noindex or a robots.txt Disallow rule is applied by multiple layers, or removing it would expose private, duplicate, or staging content.
 
 
 
 
 
 
 
Raw vs. Rendered HTML Checker · one finding
 
Robots.txt blocks rendering resources
 
Recommended action: Allow Googlebot to fetch the blocked JavaScript, CSS, or data resources required to render the page.
 
Fix principle: Remove every unintended noindex from its confirmed owner; absence of noindex is sufficient, while an explicit index directive cannot override another noindex because restrictive directives combine.
 
 
 
 Implementation for your setup 
 
Confirm first: The final HTML or HTTP response contains a noindex directive, including one added only by client-side script during rendering. The page is intended to be an indexable canonical URL. A robots meta tag or X-Robots-Tag intended to keep the page indexable is neutralized by a conflicting directive elsewhere, because directives combine using the most restrictive rule. Robots.txt disallows the URL itself, or disallows a resource the page depends on to render, so the crawler cannot reach or fully evaluate the intended indexable page.
 
Do not apply when: Exclusion is intentional for the page type, environment, or workflow state. The directive appears only on a noncanonical or otherwise ineligible URL. Robots.txt does not disallow the URL or the resources it needs to render, and the effective combination of every directive already resolves to the intended indexable state.
 
Likely control points: cms-app · server · edge-cdn
 
   
Choose the layer that owns the final response.
 
 
 
Generic HTTP / HTML
 
Status: supported · Location: The application, server, or edge owner that emits the directive, or the robots.txt file at the site root
 
Steps
  1. Follow redirects, identify the exact owner of each unintended robots/googlebot meta or X-Robots-Tag noindex, and remove it only at that owner.
  2. Return the intended canonical page with a crawlable 200 response, align its canonical, and purge the caches that can retain the directive.
  3. If a robots meta tag or X-Robots-Tag is present but rendered ineffective by a conflicting directive elsewhere, remove the actual unwanted restrictive directive rather than adding a permissive one to compete with it — the most restrictive rule always wins. Google also honors a robots meta tag placed outside <head>, so an out-of-head placement is a specification and cross-crawler risk to correct, not by itself proof Google is ignoring the directive.
  4. If robots.txt disallows the URL itself, or disallows a resource (such as CSS or JS) the page needs to render its content, correct only the specific Disallow rule at the robots.txt file that owns it — keep the rule as narrow as its original intent, and remember Disallow blocks crawling, not indexing: a disallowed URL can still be indexed if discovered elsewhere.
  5. Keep the URL crawlable so Google can observe the removal.
  
Verify on this platform
 
  • After redirects and cache purge, inspect every robots and googlebot meta tag plus every X-Robots-Tag value on the final response.
  • Fetch and parse robots.txt for every group that applies to the relevant user-agent — Google consolidates every group matching the same user-agent token into one effective ruleset, though not every crawler does — and confirm the URL and its critical rendering resources are not disallowed.
  • Use Search Console URL Inspection’s live test on the production URL, then request indexing when appropriate.
 
Rollback
  1. Restore the prior directive or robots.txt rule if the page or a resource it needs was exposed or blocked unintentionally, then correct the underlying publication rule before trying again.
 
Caveats
  • Do not add index as a counter-directive: the most restrictive directive applies, so another noindex still wins.
  • The live test checks current accessibility; it does not guarantee selection, canonical choice, or indexing.
  • Google’s own parser combines every robots.txt group matching the same user-agent token into one effective ruleset, but many other crawlers and Robots Exclusion Protocol implementations honor only the first matching group — treat a directive split across groups as a real interoperability risk even when Google itself is unaffected.
  • If the page combines a canonical to a different URL with a noindex directive, remove the noindex only if this URL itself should be indexable; if the canonical target is the one meant to be indexed, keep the noindex here and verify the canonical target separately rather than treating its indexability as confirmed by removing this noindex.
 
Official sources
 
 
WordPress
 
Status: supported · Location: Global Settings → Reading/blog_public, or the scoped plugin/theme callback that owns wp_robots
 
Steps
  1. If WordPress core globally owns the directive, confirm the scope and change Settings → Reading so blog_public permits search-engine visibility.
  2. For a scoped page-type or URL rule, identify and change the plugin or theme callback filtering wp_robots or invoking the core noindex behavior; do not invent a plugin UI.
  3. Purge page, object, host, and edge caches that can retain the old output.
  
Verify on this platform
 
  • While logged out, follow redirects and inspect all robots/googlebot meta plus X-Robots-Tag values on the final public response.
 
Rollback
  1. Restore the previous visibility or plugin setting if unintended pages become indexable.
 
Caveats
  • Do not use the global Reading setting to solve a scoped plugin or theme rule.
  • WordPress exposes the wp_robots API, but a third-party owner’s exact UI is not verified here.
  • Robots.txt is a separate control point from this meta/header directive — correct a Disallow rule using the generic-http-html guidance above regardless of which CMS serves the site.
 
Official sources
 
 
Cloudflare Workers / Rules
 
Status: supported · Location: Confirmed Response Header Transform Rule or Worker emitter
 
Steps
  1. Use Cloudflare Trace and configuration review to confirm which Transform Rule or Worker adds the final X-Robots-Tag and account for response-header rule ordering.
  2. Narrow or remove only that confirmed edge emitter; in a Worker, clone the response before modifying its headers.
  3. Purge the affected cache entries and leave any valid origin-owned robots header intact.
  
Verify on this platform
 
  • Compare origin and final Cloudflare responses after redirects, then confirm every final robots header and meta directive is free of unintended noindex.
 
Rollback
  1. Restore the prior edge rule if the scope change exposes excluded routes, then replace it with a narrower condition.
 
Caveats
  • Never blanket-delete a valid origin X-Robots-Tag when Cloudflare is not the confirmed emitter.
  • Later response-header rules can override earlier changes, so verify the final rule order and response.
  • Robots.txt is a separate control point from this response-header directive — correct a Disallow rule using the generic-http-html guidance above.
 
Official sources
 
 
Next.js / Vercel
 
Status: supported · Location: App Router metadata/generateMetadata, Pages Router next/head, or next.config headers()
 
Steps
  1. In the App Router, remove the unintended noindex from static metadata.robots or generateMetadata at the route that owns it.
  2. In the Pages Router, correct the owning next/head robots meta; for an X-Robots-Tag, correct the scoped next.config headers() rule.
  3. Deploy to the intended production environment and purge or bypass relevant caches before verification.
  
Verify on this platform
 
  • Inspect all final robots/googlebot meta and X-Robots-Tag values after redirects on the current production deployment.
 
Rollback
  1. Revert the route metadata, Head output, or headers() rule if the deployment exposes a route that should remain excluded.
 
Caveats
  • Vercel intentionally serves X-Robots-Tag: noindex for Preview Deployments and outdated Production Deployments; preserve that protection.
  • Do not diagnose an intentional preview response as a production metadata defect.
  • Robots.txt (a static file or a route handler such as app/robots.ts) is a separate control point from this metadata/header directive — correct a Disallow rule using the generic-http-html guidance above.
 
Official sources
 
 
Platform-managed / ask the vendor
 
Status: platform-managed · Location: Vendor-owned publication, visibility, or response-header control
 
Steps
  1. Ask the vendor to identify the exact global or scoped control that emits noindex and remove it only for the confirmed public canonical URL.
  
Verify on this platform
 
  • Follow redirects and inspect all robots/googlebot meta and X-Robots-Tag values on the final public response, then use the Search Console live test.
 
Rollback
  1. Restore the vendor visibility control if an unintended page becomes public while the owning rule is corrected.
 
Caveats
  • Do not add index to compete with a noindex emitted elsewhere.
  • Keep the URL crawlable long enough for search engines to observe the removal.
  • Ask the vendor to confirm whether it also owns robots.txt for the domain — a Disallow rule there is a separate control point from a meta/header directive.
 
Official sources
 
 
 
 
 How to verify 
 
  1. Follow redirects and confirm a crawlable 200 final response with no noindex in any robots/googlebot meta or X-Robots-Tag value.
  2. Confirm the canonical points to the intended URL and relevant caches no longer serve the directive.
  3. Fetch and parse robots.txt for the applicable user-agent group(s) and confirm the URL and its critical rendering resources are not disallowed.
  4. Rerun SEO Site Audit Crawler, On-Page SEO Checker, Google Index Checker, Render Gap, or Robots.txt Tester (whichever surfaced the finding), and use Search Console URL Inspection’s live test for Google’s current view.
 
Escalate when
 
Escalate when page ownership or publication intent is unclear, noindex or a robots.txt Disallow rule is applied by multiple layers, or removing it would expose private, duplicate, or staging content.
 
 
 
 
 
 
 
Raw vs. Rendered HTML Checker · one finding
 
Initial and rendered canonicals conflict
 
Recommended action: Choose the preferred absolute URL and make the initial and rendered canonical tags point to it.
 
Fix principle: Align every canonical signal for a page — the HTML <link rel=canonical>, an HTTP Link header, the post-render DOM, and each page's self-reference inside an hreflang cluster — on one confirmed intended URL; a conflict anywhere in that chain is resolved at its owning layer, never papered over by adding another canonical downstream.
 
 
 
 Implementation for your setup 
 
Confirm first: The page emits zero, more than one, or mutually disagreeing canonical signals across its HTML head, HTTP response header, or post-render DOM. A present canonical signal is relative, points to a URL that does not return a live 200 response, sits outside <head> where crawlers may not honor it, or only appears after client-side JavaScript runs.
 
Do not apply when: Exactly one absolute canonical URL is declared consistently across the HTML head, any HTTP header, and the rendered DOM, and that target itself returns 200. The apparent second reference is a distinct, valid annotation — an hreflang alternate, a pagination rel=next/prev, or another non-canonical link — not a competing canonical claim for the same page.
 
Likely control points: cms-app · server · edge-cdn
 
   
Choose the layer that owns the final response.
 
 
 
Generic HTTP / HTML
 
Status: supported · Location: Origin template, application server, or the layer that emits the HTTP Link header
 
Steps
  1. Enumerate every canonical signal for the URL — the HTML <link rel="canonical">, any HTTP Link: rel="canonical" response header, and the post-render DOM — and identify which layer emits each one.
  2. Choose exactly one intended absolute canonical URL per page and make every signal reproduce it verbatim; never declare a relative canonical, and never let a sitemap entry, redirect target, or hreflang alternate imply a different URL than the declared canonical.
  3. Correct or remove the emitting layer for any conflicting or duplicate signal at its source. Do not add a second, "corrective" canonical on top of an existing one.
  4. Confirm the canonical target itself returns a live 200 response on the protocol and host the site actually serves, not a redirect or error.
  
Verify on this platform
 
  • Fetch the raw response and inspect <head> for exactly one absolute canonical link, then check response headers for at most one agreeing Link: rel="canonical".
  • Confirm the canonical target itself returns 200 without redirecting, then use Search Console URL Inspection to compare the user-declared canonical against the Google-selected canonical.
 
Rollback
  1. Restore the previous canonical annotation or header if the correction points crawlers away from a URL that needs to stay indexed, then re-diagnose the true conflicting layer before trying again.
 
Caveats
  • A declared canonical is a hint, not a directive: Google may select a different URL as canonical for various reasons even when every signal you control agrees.
  • Don't specify different canonical URLs for the same page using different mechanisms (for example, one URL in a sitemap and a different one via rel=canonical) — the conflict itself is the defect, not the presence of any one mechanism.
  • If the page belongs to an hreflang cluster, each localized URL must canonicalize to itself (or its own best-language substitute), not to the primary-language version.
 
Official sources
 
 
WordPress
 
Status: supported · Location: Theme output via the wp_head hook, or the single plugin/theme layer that has taken over the canonical tag
 
Steps
  1. Confirm WordPress core's native rel_canonical() output — hooked on wp_head — is the only source of the canonical tag, or that exactly one SEO plugin or theme has deliberately taken over that responsibility. Never leave two layers emitting a tag for the same page.
  2. If a plugin, theme, or manual template edit adds a second <link rel="canonical"> or a conflicting header, correct or remove it at that specific owning layer; do not add a third tag to compensate.
  3. Confirm the intended canonical target is the live, indexable URL the site actually wants, not a query-parameter, paginated, or otherwise non-canonical variant.
  
Verify on this platform
 
  • While logged out, view the public HTML source once and confirm a single <link rel="canonical"> matching the intended URL, then confirm no HTTP Link header contradicts it.
 
Rollback
  1. Restore the previous theme or plugin canonical configuration if removing a tag causes an unintended page to lose its canonical reference, then correct the true conflicting layer before trying again.
 
Caveats
  • Do not invent a specific SEO plugin's settings path: WordPress core exposes wp_get_canonical_url() and rel_canonical() on wp_head, but which plugin or theme, if any, has overridden that output is not verified here.
  • A page builder or headless WordPress frontend is owner-managed; use that system's own verified workflow instead of assuming core theme output controls the response.
 
Official sources
 
 
Next.js / Vercel
 
Status: supported · Location: metadata.alternates.canonical / generateMetadata in the App Router, or next/head output in the Pages Router
 
Steps
  1. Set metadata.alternates.canonical (or the equivalent value returned from generateMetadata) to one absolute intended URL per App Router route; in the Pages Router, emit exactly one canonical <link> via next/head.
  2. Set metadataBase once at the root layout so relative canonical values resolve against the correct production host, instead of leaving canonical relative or inconsistent between preview and production domains.
  3. Do not also emit a second canonical tag from a component, a custom document, or an edge Proxy/Middleware response header once the metadata API owns the output.
  4. If the route belongs to an hreflang cluster, pair alternates.canonical with alternates.languages so each localized route canonicalizes to itself.
  
Verify on this platform
 
  • Fetch the deployed production route without executing JavaScript, confirm exactly one <link rel="canonical"> with the intended absolute URL, then rerun Canonicalization Checker or Render Gap on the same URL.
 
Rollback
  1. Revert the metadata export or route segment if the deployment changes the canonical for a route that needs to keep its prior target, then correct the actual conflicting layer before redeploying.
 
Caveats
  • metadataBase only fills in relative values; an already-absolute canonical value is used as-is and ignores metadataBase.
  • Confirm the production deployment domain matches the intended canonical host — a Preview Deployment URL is never the intended canonical target.
 
Official sources
 
 
Shopify
 
Status: supported · Location: Online Store theme.liquid head output via the canonical_url Liquid object
 
Steps
  1. Duplicate the active theme and confirm theme.liquid emits exactly one <link rel="canonical" href="{{ canonical_url }}" /> in the head; Shopify's canonical_url object already resolves to the platform's intended canonical for standard product, collection, and content pages.
  2. If a second canonical tag is present — added by an app embed, a theme customization, or a duplicated snippet — remove it at that specific source rather than editing canonical_url itself.
  3. Preview representative product, collection, and content routes before publishing the corrected duplicate theme.
  
Verify on this platform
 
  • Inspect the published storefront response without browser execution and confirm a single canonical tag reflecting canonical_url on each route type.
 
Rollback
  1. Republish the previous theme if the corrected theme regresses canonical output or storefront functionality.
 
Caveats
  • These steps apply only to Shopify Online Store Liquid/JSON themes using the canonical_url object.
  • An app-owned storefront, a Hydrogen implementation, or an app that injects its own canonical tag is owner-managed; verify that system's own workflow rather than assuming theme.liquid is the only emitter.
 
Official sources
 
 
Platform-managed / ask the vendor
 
Status: platform-managed · Location: Vendor-owned page builder, headless frontend, or hosted platform template
 
Implementation is controlled by the platform or vendor.
  
Verify on this platform
 
  • Ask the vendor to confirm which single layer emits the canonical tag and header for the URL, then compare the user-declared and Google-selected canonical in Search Console URL Inspection.
  
Caveats
  • Escalate when the vendor cannot identify or expose the layer that emits a conflicting or duplicate canonical signal.
  • Do not accept a claim that the canonical is correct without one production-URL response showing a single agreeing signal.
 
Official sources
 
 
 
 
 How to verify 
 
  1. Fetch the raw response and confirm exactly one canonical signal (the HTML tag and, if present, the HTTP header) names the same absolute, live URL.
  2. Confirm the canonical target itself returns 200 without redirecting.
  3. Compare the user-declared canonical against Google's selected canonical in Search Console URL Inspection.
  4. Rerun the finding's originating tool (Canonicalization Checker, On-Page SEO Checker, SEO Site Audit Crawler, Render Gap, Google Index Checker, or HTTP Header Checker) on the same production URL.
 
Escalate when
 
Escalate when ownership of the emitting layer is unclear, more than one system claims to own the canonical output, or Google's selected canonical keeps diverging from the declared canonical after every signal you control has been made consistent.
 
 
 
 
 
 
 
Raw vs. Rendered HTML Checker · one finding
 
JavaScript overwrites the canonical
 
Recommended action: Keep one canonical in the initial HTML and stop client code from replacing it after render.
 
Fix principle: Align every canonical signal for a page — the HTML <link rel=canonical>, an HTTP Link header, the post-render DOM, and each page's self-reference inside an hreflang cluster — on one confirmed intended URL; a conflict anywhere in that chain is resolved at its owning layer, never papered over by adding another canonical downstream.
 
 
 
 Implementation for your setup 
 
Confirm first: The page emits zero, more than one, or mutually disagreeing canonical signals across its HTML head, HTTP response header, or post-render DOM. A present canonical signal is relative, points to a URL that does not return a live 200 response, sits outside <head> where crawlers may not honor it, or only appears after client-side JavaScript runs.
 
Do not apply when: Exactly one absolute canonical URL is declared consistently across the HTML head, any HTTP header, and the rendered DOM, and that target itself returns 200. The apparent second reference is a distinct, valid annotation — an hreflang alternate, a pagination rel=next/prev, or another non-canonical link — not a competing canonical claim for the same page.
 
Likely control points: cms-app · server · edge-cdn
 
   
Choose the layer that owns the final response.
 
 
 
Generic HTTP / HTML
 
Status: supported · Location: Origin template, application server, or the layer that emits the HTTP Link header
 
Steps
  1. Enumerate every canonical signal for the URL — the HTML <link rel="canonical">, any HTTP Link: rel="canonical" response header, and the post-render DOM — and identify which layer emits each one.
  2. Choose exactly one intended absolute canonical URL per page and make every signal reproduce it verbatim; never declare a relative canonical, and never let a sitemap entry, redirect target, or hreflang alternate imply a different URL than the declared canonical.
  3. Correct or remove the emitting layer for any conflicting or duplicate signal at its source. Do not add a second, "corrective" canonical on top of an existing one.
  4. Confirm the canonical target itself returns a live 200 response on the protocol and host the site actually serves, not a redirect or error.
  
Verify on this platform
 
  • Fetch the raw response and inspect <head> for exactly one absolute canonical link, then check response headers for at most one agreeing Link: rel="canonical".
  • Confirm the canonical target itself returns 200 without redirecting, then use Search Console URL Inspection to compare the user-declared canonical against the Google-selected canonical.
 
Rollback
  1. Restore the previous canonical annotation or header if the correction points crawlers away from a URL that needs to stay indexed, then re-diagnose the true conflicting layer before trying again.
 
Caveats
  • A declared canonical is a hint, not a directive: Google may select a different URL as canonical for various reasons even when every signal you control agrees.
  • Don't specify different canonical URLs for the same page using different mechanisms (for example, one URL in a sitemap and a different one via rel=canonical) — the conflict itself is the defect, not the presence of any one mechanism.
  • If the page belongs to an hreflang cluster, each localized URL must canonicalize to itself (or its own best-language substitute), not to the primary-language version.
 
Official sources
 
 
WordPress
 
Status: supported · Location: Theme output via the wp_head hook, or the single plugin/theme layer that has taken over the canonical tag
 
Steps
  1. Confirm WordPress core's native rel_canonical() output — hooked on wp_head — is the only source of the canonical tag, or that exactly one SEO plugin or theme has deliberately taken over that responsibility. Never leave two layers emitting a tag for the same page.
  2. If a plugin, theme, or manual template edit adds a second <link rel="canonical"> or a conflicting header, correct or remove it at that specific owning layer; do not add a third tag to compensate.
  3. Confirm the intended canonical target is the live, indexable URL the site actually wants, not a query-parameter, paginated, or otherwise non-canonical variant.
  
Verify on this platform
 
  • While logged out, view the public HTML source once and confirm a single <link rel="canonical"> matching the intended URL, then confirm no HTTP Link header contradicts it.
 
Rollback
  1. Restore the previous theme or plugin canonical configuration if removing a tag causes an unintended page to lose its canonical reference, then correct the true conflicting layer before trying again.
 
Caveats
  • Do not invent a specific SEO plugin's settings path: WordPress core exposes wp_get_canonical_url() and rel_canonical() on wp_head, but which plugin or theme, if any, has overridden that output is not verified here.
  • A page builder or headless WordPress frontend is owner-managed; use that system's own verified workflow instead of assuming core theme output controls the response.
 
Official sources
 
 
Next.js / Vercel
 
Status: supported · Location: metadata.alternates.canonical / generateMetadata in the App Router, or next/head output in the Pages Router
 
Steps
  1. Set metadata.alternates.canonical (or the equivalent value returned from generateMetadata) to one absolute intended URL per App Router route; in the Pages Router, emit exactly one canonical <link> via next/head.
  2. Set metadataBase once at the root layout so relative canonical values resolve against the correct production host, instead of leaving canonical relative or inconsistent between preview and production domains.
  3. Do not also emit a second canonical tag from a component, a custom document, or an edge Proxy/Middleware response header once the metadata API owns the output.
  4. If the route belongs to an hreflang cluster, pair alternates.canonical with alternates.languages so each localized route canonicalizes to itself.
  
Verify on this platform
 
  • Fetch the deployed production route without executing JavaScript, confirm exactly one <link rel="canonical"> with the intended absolute URL, then rerun Canonicalization Checker or Render Gap on the same URL.
 
Rollback
  1. Revert the metadata export or route segment if the deployment changes the canonical for a route that needs to keep its prior target, then correct the actual conflicting layer before redeploying.
 
Caveats
  • metadataBase only fills in relative values; an already-absolute canonical value is used as-is and ignores metadataBase.
  • Confirm the production deployment domain matches the intended canonical host — a Preview Deployment URL is never the intended canonical target.
 
Official sources
 
 
Shopify
 
Status: supported · Location: Online Store theme.liquid head output via the canonical_url Liquid object
 
Steps
  1. Duplicate the active theme and confirm theme.liquid emits exactly one <link rel="canonical" href="{{ canonical_url }}" /> in the head; Shopify's canonical_url object already resolves to the platform's intended canonical for standard product, collection, and content pages.
  2. If a second canonical tag is present — added by an app embed, a theme customization, or a duplicated snippet — remove it at that specific source rather than editing canonical_url itself.
  3. Preview representative product, collection, and content routes before publishing the corrected duplicate theme.
  
Verify on this platform
 
  • Inspect the published storefront response without browser execution and confirm a single canonical tag reflecting canonical_url on each route type.
 
Rollback
  1. Republish the previous theme if the corrected theme regresses canonical output or storefront functionality.
 
Caveats
  • These steps apply only to Shopify Online Store Liquid/JSON themes using the canonical_url object.
  • An app-owned storefront, a Hydrogen implementation, or an app that injects its own canonical tag is owner-managed; verify that system's own workflow rather than assuming theme.liquid is the only emitter.
 
Official sources
 
 
Platform-managed / ask the vendor
 
Status: platform-managed · Location: Vendor-owned page builder, headless frontend, or hosted platform template
 
Implementation is controlled by the platform or vendor.
  
Verify on this platform
 
  • Ask the vendor to confirm which single layer emits the canonical tag and header for the URL, then compare the user-declared and Google-selected canonical in Search Console URL Inspection.
  
Caveats
  • Escalate when the vendor cannot identify or expose the layer that emits a conflicting or duplicate canonical signal.
  • Do not accept a claim that the canonical is correct without one production-URL response showing a single agreeing signal.
 
Official sources
 
 
 
 
 How to verify 
 
  1. Fetch the raw response and confirm exactly one canonical signal (the HTML tag and, if present, the HTTP header) names the same absolute, live URL.
  2. Confirm the canonical target itself returns 200 without redirecting.
  3. Compare the user-declared canonical against Google's selected canonical in Search Console URL Inspection.
  4. Rerun the finding's originating tool (Canonicalization Checker, On-Page SEO Checker, SEO Site Audit Crawler, Render Gap, Google Index Checker, or HTTP Header Checker) on the same production URL.
 
Escalate when
 
Escalate when ownership of the emitting layer is unclear, more than one system claims to own the canonical output, or Google's selected canonical keeps diverging from the declared canonical after every signal you control has been made consistent.
 
 
 
 
 
 
 
Raw vs. Rendered HTML Checker · one finding
 
Canonical exists only after rendering
 
Recommended action: Move the canonical tag into the initial HTML instead of adding it only after JavaScript runs.
 
Fix principle: Align every canonical signal for a page — the HTML <link rel=canonical>, an HTTP Link header, the post-render DOM, and each page's self-reference inside an hreflang cluster — on one confirmed intended URL; a conflict anywhere in that chain is resolved at its owning layer, never papered over by adding another canonical downstream.
 
 
 
 Implementation for your setup 
 
Confirm first: The page emits zero, more than one, or mutually disagreeing canonical signals across its HTML head, HTTP response header, or post-render DOM. A present canonical signal is relative, points to a URL that does not return a live 200 response, sits outside <head> where crawlers may not honor it, or only appears after client-side JavaScript runs.
 
Do not apply when: Exactly one absolute canonical URL is declared consistently across the HTML head, any HTTP header, and the rendered DOM, and that target itself returns 200. The apparent second reference is a distinct, valid annotation — an hreflang alternate, a pagination rel=next/prev, or another non-canonical link — not a competing canonical claim for the same page.
 
Likely control points: cms-app · server · edge-cdn
 
   
Choose the layer that owns the final response.
 
 
 
Generic HTTP / HTML
 
Status: supported · Location: Origin template, application server, or the layer that emits the HTTP Link header
 
Steps
  1. Enumerate every canonical signal for the URL — the HTML <link rel="canonical">, any HTTP Link: rel="canonical" response header, and the post-render DOM — and identify which layer emits each one.
  2. Choose exactly one intended absolute canonical URL per page and make every signal reproduce it verbatim; never declare a relative canonical, and never let a sitemap entry, redirect target, or hreflang alternate imply a different URL than the declared canonical.
  3. Correct or remove the emitting layer for any conflicting or duplicate signal at its source. Do not add a second, "corrective" canonical on top of an existing one.
  4. Confirm the canonical target itself returns a live 200 response on the protocol and host the site actually serves, not a redirect or error.
  
Verify on this platform
 
  • Fetch the raw response and inspect <head> for exactly one absolute canonical link, then check response headers for at most one agreeing Link: rel="canonical".
  • Confirm the canonical target itself returns 200 without redirecting, then use Search Console URL Inspection to compare the user-declared canonical against the Google-selected canonical.
 
Rollback
  1. Restore the previous canonical annotation or header if the correction points crawlers away from a URL that needs to stay indexed, then re-diagnose the true conflicting layer before trying again.
 
Caveats
  • A declared canonical is a hint, not a directive: Google may select a different URL as canonical for various reasons even when every signal you control agrees.
  • Don't specify different canonical URLs for the same page using different mechanisms (for example, one URL in a sitemap and a different one via rel=canonical) — the conflict itself is the defect, not the presence of any one mechanism.
  • If the page belongs to an hreflang cluster, each localized URL must canonicalize to itself (or its own best-language substitute), not to the primary-language version.
 
Official sources
 
 
WordPress
 
Status: supported · Location: Theme output via the wp_head hook, or the single plugin/theme layer that has taken over the canonical tag
 
Steps
  1. Confirm WordPress core's native rel_canonical() output — hooked on wp_head — is the only source of the canonical tag, or that exactly one SEO plugin or theme has deliberately taken over that responsibility. Never leave two layers emitting a tag for the same page.
  2. If a plugin, theme, or manual template edit adds a second <link rel="canonical"> or a conflicting header, correct or remove it at that specific owning layer; do not add a third tag to compensate.
  3. Confirm the intended canonical target is the live, indexable URL the site actually wants, not a query-parameter, paginated, or otherwise non-canonical variant.
  
Verify on this platform
 
  • While logged out, view the public HTML source once and confirm a single <link rel="canonical"> matching the intended URL, then confirm no HTTP Link header contradicts it.
 
Rollback
  1. Restore the previous theme or plugin canonical configuration if removing a tag causes an unintended page to lose its canonical reference, then correct the true conflicting layer before trying again.
 
Caveats
  • Do not invent a specific SEO plugin's settings path: WordPress core exposes wp_get_canonical_url() and rel_canonical() on wp_head, but which plugin or theme, if any, has overridden that output is not verified here.
  • A page builder or headless WordPress frontend is owner-managed; use that system's own verified workflow instead of assuming core theme output controls the response.
 
Official sources
 
 
Next.js / Vercel
 
Status: supported · Location: metadata.alternates.canonical / generateMetadata in the App Router, or next/head output in the Pages Router
 
Steps
  1. Set metadata.alternates.canonical (or the equivalent value returned from generateMetadata) to one absolute intended URL per App Router route; in the Pages Router, emit exactly one canonical <link> via next/head.
  2. Set metadataBase once at the root layout so relative canonical values resolve against the correct production host, instead of leaving canonical relative or inconsistent between preview and production domains.
  3. Do not also emit a second canonical tag from a component, a custom document, or an edge Proxy/Middleware response header once the metadata API owns the output.
  4. If the route belongs to an hreflang cluster, pair alternates.canonical with alternates.languages so each localized route canonicalizes to itself.
  
Verify on this platform
 
  • Fetch the deployed production route without executing JavaScript, confirm exactly one <link rel="canonical"> with the intended absolute URL, then rerun Canonicalization Checker or Render Gap on the same URL.
 
Rollback
  1. Revert the metadata export or route segment if the deployment changes the canonical for a route that needs to keep its prior target, then correct the actual conflicting layer before redeploying.
 
Caveats
  • metadataBase only fills in relative values; an already-absolute canonical value is used as-is and ignores metadataBase.
  • Confirm the production deployment domain matches the intended canonical host — a Preview Deployment URL is never the intended canonical target.
 
Official sources
 
 
Shopify
 
Status: supported · Location: Online Store theme.liquid head output via the canonical_url Liquid object
 
Steps
  1. Duplicate the active theme and confirm theme.liquid emits exactly one <link rel="canonical" href="{{ canonical_url }}" /> in the head; Shopify's canonical_url object already resolves to the platform's intended canonical for standard product, collection, and content pages.
  2. If a second canonical tag is present — added by an app embed, a theme customization, or a duplicated snippet — remove it at that specific source rather than editing canonical_url itself.
  3. Preview representative product, collection, and content routes before publishing the corrected duplicate theme.
  
Verify on this platform
 
  • Inspect the published storefront response without browser execution and confirm a single canonical tag reflecting canonical_url on each route type.
 
Rollback
  1. Republish the previous theme if the corrected theme regresses canonical output or storefront functionality.
 
Caveats
  • These steps apply only to Shopify Online Store Liquid/JSON themes using the canonical_url object.
  • An app-owned storefront, a Hydrogen implementation, or an app that injects its own canonical tag is owner-managed; verify that system's own workflow rather than assuming theme.liquid is the only emitter.
 
Official sources
 
 
Platform-managed / ask the vendor
 
Status: platform-managed · Location: Vendor-owned page builder, headless frontend, or hosted platform template
 
Implementation is controlled by the platform or vendor.
  
Verify on this platform
 
  • Ask the vendor to confirm which single layer emits the canonical tag and header for the URL, then compare the user-declared and Google-selected canonical in Search Console URL Inspection.
  
Caveats
  • Escalate when the vendor cannot identify or expose the layer that emits a conflicting or duplicate canonical signal.
  • Do not accept a claim that the canonical is correct without one production-URL response showing a single agreeing signal.
 
Official sources
 
 
 
 
 How to verify 
 
  1. Fetch the raw response and confirm exactly one canonical signal (the HTML tag and, if present, the HTTP header) names the same absolute, live URL.
  2. Confirm the canonical target itself returns 200 without redirecting.
  3. Compare the user-declared canonical against Google's selected canonical in Search Console URL Inspection.
  4. Rerun the finding's originating tool (Canonicalization Checker, On-Page SEO Checker, SEO Site Audit Crawler, Render Gap, Google Index Checker, or HTTP Header Checker) on the same production URL.
 
Escalate when
 
Escalate when ownership of the emitting layer is unclear, more than one system claims to own the canonical output, or Google's selected canonical keeps diverging from the declared canonical after every signal you control has been made consistent.
 
 
 
 
 
 
 
Raw vs. Rendered HTML Checker · one finding
 
Initial HTML contains conflicting canonicals
 
Recommended action: Emit one canonical URL in the initial HTML instead of relying on JavaScript to repair conflicting declarations.
 
Fix principle: Align every canonical signal for a page — the HTML <link rel=canonical>, an HTTP Link header, the post-render DOM, and each page's self-reference inside an hreflang cluster — on one confirmed intended URL; a conflict anywhere in that chain is resolved at its owning layer, never papered over by adding another canonical downstream.
 
 
 
 Implementation for your setup 
 
Confirm first: The page emits zero, more than one, or mutually disagreeing canonical signals across its HTML head, HTTP response header, or post-render DOM. A present canonical signal is relative, points to a URL that does not return a live 200 response, sits outside <head> where crawlers may not honor it, or only appears after client-side JavaScript runs.
 
Do not apply when: Exactly one absolute canonical URL is declared consistently across the HTML head, any HTTP header, and the rendered DOM, and that target itself returns 200. The apparent second reference is a distinct, valid annotation — an hreflang alternate, a pagination rel=next/prev, or another non-canonical link — not a competing canonical claim for the same page.
 
Likely control points: cms-app · server · edge-cdn
 
   
Choose the layer that owns the final response.
 
 
 
Generic HTTP / HTML
 
Status: supported · Location: Origin template, application server, or the layer that emits the HTTP Link header
 
Steps
  1. Enumerate every canonical signal for the URL — the HTML <link rel="canonical">, any HTTP Link: rel="canonical" response header, and the post-render DOM — and identify which layer emits each one.
  2. Choose exactly one intended absolute canonical URL per page and make every signal reproduce it verbatim; never declare a relative canonical, and never let a sitemap entry, redirect target, or hreflang alternate imply a different URL than the declared canonical.
  3. Correct or remove the emitting layer for any conflicting or duplicate signal at its source. Do not add a second, "corrective" canonical on top of an existing one.
  4. Confirm the canonical target itself returns a live 200 response on the protocol and host the site actually serves, not a redirect or error.
  
Verify on this platform
 
  • Fetch the raw response and inspect <head> for exactly one absolute canonical link, then check response headers for at most one agreeing Link: rel="canonical".
  • Confirm the canonical target itself returns 200 without redirecting, then use Search Console URL Inspection to compare the user-declared canonical against the Google-selected canonical.
 
Rollback
  1. Restore the previous canonical annotation or header if the correction points crawlers away from a URL that needs to stay indexed, then re-diagnose the true conflicting layer before trying again.
 
Caveats
  • A declared canonical is a hint, not a directive: Google may select a different URL as canonical for various reasons even when every signal you control agrees.
  • Don't specify different canonical URLs for the same page using different mechanisms (for example, one URL in a sitemap and a different one via rel=canonical) — the conflict itself is the defect, not the presence of any one mechanism.
  • If the page belongs to an hreflang cluster, each localized URL must canonicalize to itself (or its own best-language substitute), not to the primary-language version.
 
Official sources
 
 
WordPress
 
Status: supported · Location: Theme output via the wp_head hook, or the single plugin/theme layer that has taken over the canonical tag
 
Steps
  1. Confirm WordPress core's native rel_canonical() output — hooked on wp_head — is the only source of the canonical tag, or that exactly one SEO plugin or theme has deliberately taken over that responsibility. Never leave two layers emitting a tag for the same page.
  2. If a plugin, theme, or manual template edit adds a second <link rel="canonical"> or a conflicting header, correct or remove it at that specific owning layer; do not add a third tag to compensate.
  3. Confirm the intended canonical target is the live, indexable URL the site actually wants, not a query-parameter, paginated, or otherwise non-canonical variant.
  
Verify on this platform
 
  • While logged out, view the public HTML source once and confirm a single <link rel="canonical"> matching the intended URL, then confirm no HTTP Link header contradicts it.
 
Rollback
  1. Restore the previous theme or plugin canonical configuration if removing a tag causes an unintended page to lose its canonical reference, then correct the true conflicting layer before trying again.
 
Caveats
  • Do not invent a specific SEO plugin's settings path: WordPress core exposes wp_get_canonical_url() and rel_canonical() on wp_head, but which plugin or theme, if any, has overridden that output is not verified here.
  • A page builder or headless WordPress frontend is owner-managed; use that system's own verified workflow instead of assuming core theme output controls the response.
 
Official sources
 
 
Next.js / Vercel
 
Status: supported · Location: metadata.alternates.canonical / generateMetadata in the App Router, or next/head output in the Pages Router
 
Steps
  1. Set metadata.alternates.canonical (or the equivalent value returned from generateMetadata) to one absolute intended URL per App Router route; in the Pages Router, emit exactly one canonical <link> via next/head.
  2. Set metadataBase once at the root layout so relative canonical values resolve against the correct production host, instead of leaving canonical relative or inconsistent between preview and production domains.
  3. Do not also emit a second canonical tag from a component, a custom document, or an edge Proxy/Middleware response header once the metadata API owns the output.
  4. If the route belongs to an hreflang cluster, pair alternates.canonical with alternates.languages so each localized route canonicalizes to itself.
  
Verify on this platform
 
  • Fetch the deployed production route without executing JavaScript, confirm exactly one <link rel="canonical"> with the intended absolute URL, then rerun Canonicalization Checker or Render Gap on the same URL.
 
Rollback
  1. Revert the metadata export or route segment if the deployment changes the canonical for a route that needs to keep its prior target, then correct the actual conflicting layer before redeploying.
 
Caveats
  • metadataBase only fills in relative values; an already-absolute canonical value is used as-is and ignores metadataBase.
  • Confirm the production deployment domain matches the intended canonical host — a Preview Deployment URL is never the intended canonical target.
 
Official sources
 
 
Shopify
 
Status: supported · Location: Online Store theme.liquid head output via the canonical_url Liquid object
 
Steps
  1. Duplicate the active theme and confirm theme.liquid emits exactly one <link rel="canonical" href="{{ canonical_url }}" /> in the head; Shopify's canonical_url object already resolves to the platform's intended canonical for standard product, collection, and content pages.
  2. If a second canonical tag is present — added by an app embed, a theme customization, or a duplicated snippet — remove it at that specific source rather than editing canonical_url itself.
  3. Preview representative product, collection, and content routes before publishing the corrected duplicate theme.
  
Verify on this platform
 
  • Inspect the published storefront response without browser execution and confirm a single canonical tag reflecting canonical_url on each route type.
 
Rollback
  1. Republish the previous theme if the corrected theme regresses canonical output or storefront functionality.
 
Caveats
  • These steps apply only to Shopify Online Store Liquid/JSON themes using the canonical_url object.
  • An app-owned storefront, a Hydrogen implementation, or an app that injects its own canonical tag is owner-managed; verify that system's own workflow rather than assuming theme.liquid is the only emitter.
 
Official sources
 
 
Platform-managed / ask the vendor
 
Status: platform-managed · Location: Vendor-owned page builder, headless frontend, or hosted platform template
 
Implementation is controlled by the platform or vendor.
  
Verify on this platform
 
  • Ask the vendor to confirm which single layer emits the canonical tag and header for the URL, then compare the user-declared and Google-selected canonical in Search Console URL Inspection.
  
Caveats
  • Escalate when the vendor cannot identify or expose the layer that emits a conflicting or duplicate canonical signal.
  • Do not accept a claim that the canonical is correct without one production-URL response showing a single agreeing signal.
 
Official sources
 
 
 
 
 How to verify 
 
  1. Fetch the raw response and confirm exactly one canonical signal (the HTML tag and, if present, the HTTP header) names the same absolute, live URL.
  2. Confirm the canonical target itself returns 200 without redirecting.
  3. Compare the user-declared canonical against Google's selected canonical in Search Console URL Inspection.
  4. Rerun the finding's originating tool (Canonicalization Checker, On-Page SEO Checker, SEO Site Audit Crawler, Render Gap, Google Index Checker, or HTTP Header Checker) on the same production URL.
 
Escalate when
 
Escalate when ownership of the emitting layer is unclear, more than one system claims to own the canonical output, or Google's selected canonical keeps diverging from the declared canonical after every signal you control has been made consistent.
 
 
 
 
 
 
 
Raw vs. Rendered HTML Checker · one finding
 
hreflang appears only after rendering
 
Recommended action: Emit every hreflang annotation in the initial HTML or HTTP headers instead of adding it only with JavaScript.
 
Fix principle: hreflang is a cluster property, not a per-page one: Google's own guidance states that if two pages don't both point to each other the annotations are ignored, and that every language version must list itself plus every other version identically. A unilateral edit on one page cannot fix a cluster — the reciprocal return tag, the self-reference, and the complete alternate set must all be corrected together, on every member, in the same change.
 
 
 
 Implementation for your setup 
 
Confirm first: An alternate page listed in the cluster does not itself list the source page back (the return/reciprocal tag is missing), so Google ignores the relationship for that pair. A page in the cluster has no self-referencing hreflang entry for its own locale and URL. An alternate target does not return a live 2xx response, redirects, or canonicalizes to a different URL than the one declared in hreflang — none of which Google will follow as the intended localized page. Pages in the same intended cluster disagree on membership: they do not all publish the same complete set of alternate URLs and locale codes. The cluster has no x-default entry despite serving a language selector, root domain, or otherwise ambiguous default experience.
 
Do not apply when: Every page in the cluster publishes an identical, reciprocal set of hreflang alternates — each page lists itself and every sibling, every sibling lists it back, and each declared target returns a live 200 response without redirecting or canonicalizing elsewhere. The cluster deliberately has no x-default because there is no ambiguous entry point (for example, every visitor arrives at an already-localized URL with no shared root or selector page).
 
Likely control points: cms-app · server · edge-cdn · managed-vendor
 
   
Choose the layer that owns the final response.
 
 
 
Generic HTTP / HTML
 
Status: supported · Location: Every page in the language cluster — origin template, application server, XML sitemap, or HTTP Link header, whichever layer emits hreflang for that site
 
Steps
  1. List every URL that is supposed to belong to the cluster, then fetch each one and record its complete hreflang set (from the HTML head, or the sitemap/Link-header equivalent, whichever the site uses).
  2. Build one target alternate set: every locale in the cluster paired with its live URL, plus a self-reference for each page's own locale, plus x-default if the cluster has an ambiguous default entry point.
  3. Publish that identical, complete set on every page in the cluster in the same change — a return tag added to only the target page while the source page stays unedited is still a broken pair.
  4. Confirm every alternate target itself returns a live 200 response on the URL declared in hreflang, without redirecting and without canonicalizing to a different URL.
  
Verify on this platform
 
  • Fetch each cluster member and confirm it lists itself plus every sibling, that every sibling lists it back, and that the set is byte-for-byte the same set of locale/URL pairs across all members.
  • Fetch each declared alternate target directly and confirm it returns 200 without redirecting, then confirm its own canonical tag matches its own URL rather than another page in or out of the cluster.
  • Rerun the returntag - hreflang checker on the full cluster (a URL or sitemap) and confirm no missing-return, missing-self, target-non-200, redirected-target, canonical-conflict, cluster-split, or x-default-gap findings remain.
 
Rollback
  1. Restore the previous hreflang set on any page where the correction removed a locale or URL still needed by another part of the site, then re-diagnose the true cluster membership before republishing.
 
Caveats
  • hreflang is a signal Google uses to select which localized URL to show, not a guarantee that the localized page will be served or ranked for that locale.
  • If two pages don't reciprocally reference each other, Google ignores the annotation for that pair entirely — a one-directional fix is not a partial fix.
  • Do not add an alternate target that is itself blocked from indexing or that never returns a 2xx response; that produces a new target-non-200 finding on the corrected cluster.
 
Official sources
 
 
WordPress
 
Status: supported · Location: Theme output via the wp_head hook, or the single plugin taking over hreflang output for a multilingual WordPress site
 
Steps
  1. Identify the one system that emits hreflang for the site — most multilingual WordPress sites use a dedicated multilingual plugin rather than manual theme code; confirm which single layer owns the output before changing anything.
  2. If hreflang is emitted manually via a theme template, build the alternate set from the site's own registered language/translation relationships so it can never drift from what the CMS itself considers the cluster, and output it identically on every member via wp_head.
  3. Whichever layer owns hreflang, treat cluster-membership drift (a page missing from the set, or a stale/removed translation still listed) as a content-management defect to fix in that system's translation-linking, not by hand-patching one page's markup.
  
Verify on this platform
 
  • While logged out, view the public HTML source of every page in the cluster and confirm each lists itself and every sibling reciprocally, then fetch each alternate target to confirm it is live and self-canonicalizing.
 
Rollback
  1. Restore the previous translation linkage or template output if the correction drops a locale relationship still needed elsewhere, then re-diagnose the true cluster membership before republishing.
 
Caveats
  • A dedicated multilingual plugin's own settings screen was not verified in this recipe — the exact admin path was not confirmed against current plugin documentation, so no specific menu or option is named here. Treat that plugin's hreflang output as platform-managed and use its own support documentation to correct translation relationships; only the fully manual, theme-emitted path above is verified.
  • If the plugin's hreflang output is itself broken (not merely a content-linking gap), that is a defect in a third-party layer this recipe cannot verify a fix for; escalate to the plugin's own support channel.
 
Official sources
 
 
Next.js / Vercel
 
Status: supported · Location: metadata.alternates.languages alongside alternates.canonical in the App Router, or the equivalent next/head output in the Pages Router
 
Steps
  1. For every route that belongs to a language cluster, set metadata.alternates.languages to the full, identical set of locale-to-URL pairs on every member route, paired with alternates.canonical set to that route's own URL.
  2. Set metadataBase once at the root layout so relative alternates.languages values resolve to the correct production host on every route rather than a preview domain.
  3. Add x-default to alternates.languages only where the cluster has an ambiguous default entry point (for example a locale-selector or root route).
  4. Do not let a route-level override replace alternates.languages with a partial set; merging in Next.js metadata replaces nested fields wholesale rather than merging them, so a child segment that sets alternates at all must set the complete set.
  
Verify on this platform
 
  • Fetch each deployed production route without executing JavaScript, confirm the emitted hreflang links are identical in membership across every cluster route and each pairs with that route's own canonical, then rerun the returntag - hreflang checker on the cluster.
 
Rollback
  1. Revert the metadata export for the affected route segment if the deployment drops a locale relationship still needed elsewhere, then correct the true cluster membership before redeploying.
 
Caveats
  • Confirm the production deployment domain matches metadataBase — a Preview Deployment URL served under a different host will not match the alternates it declares.
  • Metadata objects are merged shallowly per field across nested layouts and pages: a page that defines its own alternates.languages replaces the parent's set entirely rather than adding to it.
 
Official sources
 
 
Shopify
 
Status: supported · Location: Shopify Markets configuration, or the layout/theme.liquid content_for_header output for Markets-driven storefronts
 
Steps
  1. Confirm the storefront uses Shopify Markets: Shopify automatically adds hreflang tags built from each market's configured languages and regions via content_for_header, and keeps them in sync with each page's own canonical URL and with market changes.
  2. If the Markets configuration is missing a language, region, or domain that should be in the cluster, add it in Markets rather than hand-editing hreflang output — the automatic tags are generated from that configuration.
  3. If hreflang is emitted manually instead of through content_for_header, build the tag set dynamically from the localization object rather than hardcoding domains or resource handles, because a handle can differ per language and the head partial renders on every page.
  4. Either way, confirm each localized URL still references itself as its own canonical URL — Shopify's guidance calls this out as a prerequisite for the automatic tags to behave correctly.
  
Verify on this platform
 
  • View source on a representative page in each market/language and confirm the emitted hreflang set is complete and reciprocal, then confirm each localized URL's own canonical tag matches its own URL.
 
Rollback
  1. Revert the Markets configuration change or the manual theme edit if it drops a market or language still needed, then re-diagnose the true cluster membership before republishing.
 
Caveats
  • This applies to Shopify Markets storefronts on Online Store themes using the standard content_for_header output; a storefront that overrides this partial, uses Hydrogen, or manages locales outside Markets is not covered — verify that system's own workflow instead.
  • Shopify's own hreflang documentation does not address x-default; do not assume Shopify emits one automatically.
 
Official sources
 
 
Platform-managed / ask the vendor
 
Status: platform-managed · Location: Vendor-owned page builder, headless frontend, or hosted platform template
 
Implementation is controlled by the platform or vendor.
  
Verify on this platform
 
  • Ask the vendor to confirm which single layer emits hreflang for the cluster and how cluster membership is kept in sync across pages, then fetch every cluster member directly to confirm reciprocal, self-referencing, live-target hreflang.
  
Caveats
  • Escalate when the vendor cannot identify the layer emitting hreflang, cannot explain how it keeps membership in sync across pages, or when fetched pages keep disagreeing after every input you control has been made consistent.
  • Do not accept a claim that hreflang is correct without directly fetching each cluster member and each alternate target.
 
Official sources
 
 
 
 
 How to verify 
 
  1. Fetch every page believed to be in the cluster and record its complete hreflang set.
  2. Confirm the set is identical across every member, that every member lists itself, and that every pair is reciprocal.
  3. Confirm every declared alternate target returns a live 200 response without redirecting, and that its own canonical points to itself rather than elsewhere.
  4. Rerun the returntag - hreflang checker (and, for pages diagnosed via Raw vs. Rendered HTML Checker, confirm the same hreflang set survives rendering) on the same cluster.
 
Escalate when
 
Escalate when the system responsible for cluster membership cannot be identified, more than one system claims to manage hreflang for the same pages, or fetched pages keep disagreeing on membership after every input you control has been made consistent.
 
 
 
 
 
 
 
Raw vs. Rendered HTML Checker · one finding
 
hreflang changes after rendering
 
Recommended action: Make the initial and rendered hreflang sets identical, reciprocal, and pointed at the intended locale URLs.
 
Fix principle: hreflang is a cluster property, not a per-page one: Google's own guidance states that if two pages don't both point to each other the annotations are ignored, and that every language version must list itself plus every other version identically. A unilateral edit on one page cannot fix a cluster — the reciprocal return tag, the self-reference, and the complete alternate set must all be corrected together, on every member, in the same change.
 
 
 
 Implementation for your setup 
 
Confirm first: An alternate page listed in the cluster does not itself list the source page back (the return/reciprocal tag is missing), so Google ignores the relationship for that pair. A page in the cluster has no self-referencing hreflang entry for its own locale and URL. An alternate target does not return a live 2xx response, redirects, or canonicalizes to a different URL than the one declared in hreflang — none of which Google will follow as the intended localized page. Pages in the same intended cluster disagree on membership: they do not all publish the same complete set of alternate URLs and locale codes. The cluster has no x-default entry despite serving a language selector, root domain, or otherwise ambiguous default experience.
 
Do not apply when: Every page in the cluster publishes an identical, reciprocal set of hreflang alternates — each page lists itself and every sibling, every sibling lists it back, and each declared target returns a live 200 response without redirecting or canonicalizing elsewhere. The cluster deliberately has no x-default because there is no ambiguous entry point (for example, every visitor arrives at an already-localized URL with no shared root or selector page).
 
Likely control points: cms-app · server · edge-cdn · managed-vendor
 
   
Choose the layer that owns the final response.
 
 
 
Generic HTTP / HTML
 
Status: supported · Location: Every page in the language cluster — origin template, application server, XML sitemap, or HTTP Link header, whichever layer emits hreflang for that site
 
Steps
  1. List every URL that is supposed to belong to the cluster, then fetch each one and record its complete hreflang set (from the HTML head, or the sitemap/Link-header equivalent, whichever the site uses).
  2. Build one target alternate set: every locale in the cluster paired with its live URL, plus a self-reference for each page's own locale, plus x-default if the cluster has an ambiguous default entry point.
  3. Publish that identical, complete set on every page in the cluster in the same change — a return tag added to only the target page while the source page stays unedited is still a broken pair.
  4. Confirm every alternate target itself returns a live 200 response on the URL declared in hreflang, without redirecting and without canonicalizing to a different URL.
  
Verify on this platform
 
  • Fetch each cluster member and confirm it lists itself plus every sibling, that every sibling lists it back, and that the set is byte-for-byte the same set of locale/URL pairs across all members.
  • Fetch each declared alternate target directly and confirm it returns 200 without redirecting, then confirm its own canonical tag matches its own URL rather than another page in or out of the cluster.
  • Rerun the returntag - hreflang checker on the full cluster (a URL or sitemap) and confirm no missing-return, missing-self, target-non-200, redirected-target, canonical-conflict, cluster-split, or x-default-gap findings remain.
 
Rollback
  1. Restore the previous hreflang set on any page where the correction removed a locale or URL still needed by another part of the site, then re-diagnose the true cluster membership before republishing.
 
Caveats
  • hreflang is a signal Google uses to select which localized URL to show, not a guarantee that the localized page will be served or ranked for that locale.
  • If two pages don't reciprocally reference each other, Google ignores the annotation for that pair entirely — a one-directional fix is not a partial fix.
  • Do not add an alternate target that is itself blocked from indexing or that never returns a 2xx response; that produces a new target-non-200 finding on the corrected cluster.
 
Official sources
 
 
WordPress
 
Status: supported · Location: Theme output via the wp_head hook, or the single plugin taking over hreflang output for a multilingual WordPress site
 
Steps
  1. Identify the one system that emits hreflang for the site — most multilingual WordPress sites use a dedicated multilingual plugin rather than manual theme code; confirm which single layer owns the output before changing anything.
  2. If hreflang is emitted manually via a theme template, build the alternate set from the site's own registered language/translation relationships so it can never drift from what the CMS itself considers the cluster, and output it identically on every member via wp_head.
  3. Whichever layer owns hreflang, treat cluster-membership drift (a page missing from the set, or a stale/removed translation still listed) as a content-management defect to fix in that system's translation-linking, not by hand-patching one page's markup.
  
Verify on this platform
 
  • While logged out, view the public HTML source of every page in the cluster and confirm each lists itself and every sibling reciprocally, then fetch each alternate target to confirm it is live and self-canonicalizing.
 
Rollback
  1. Restore the previous translation linkage or template output if the correction drops a locale relationship still needed elsewhere, then re-diagnose the true cluster membership before republishing.
 
Caveats
  • A dedicated multilingual plugin's own settings screen was not verified in this recipe — the exact admin path was not confirmed against current plugin documentation, so no specific menu or option is named here. Treat that plugin's hreflang output as platform-managed and use its own support documentation to correct translation relationships; only the fully manual, theme-emitted path above is verified.
  • If the plugin's hreflang output is itself broken (not merely a content-linking gap), that is a defect in a third-party layer this recipe cannot verify a fix for; escalate to the plugin's own support channel.
 
Official sources
 
 
Next.js / Vercel
 
Status: supported · Location: metadata.alternates.languages alongside alternates.canonical in the App Router, or the equivalent next/head output in the Pages Router
 
Steps
  1. For every route that belongs to a language cluster, set metadata.alternates.languages to the full, identical set of locale-to-URL pairs on every member route, paired with alternates.canonical set to that route's own URL.
  2. Set metadataBase once at the root layout so relative alternates.languages values resolve to the correct production host on every route rather than a preview domain.
  3. Add x-default to alternates.languages only where the cluster has an ambiguous default entry point (for example a locale-selector or root route).
  4. Do not let a route-level override replace alternates.languages with a partial set; merging in Next.js metadata replaces nested fields wholesale rather than merging them, so a child segment that sets alternates at all must set the complete set.
  
Verify on this platform
 
  • Fetch each deployed production route without executing JavaScript, confirm the emitted hreflang links are identical in membership across every cluster route and each pairs with that route's own canonical, then rerun the returntag - hreflang checker on the cluster.
 
Rollback
  1. Revert the metadata export for the affected route segment if the deployment drops a locale relationship still needed elsewhere, then correct the true cluster membership before redeploying.
 
Caveats
  • Confirm the production deployment domain matches metadataBase — a Preview Deployment URL served under a different host will not match the alternates it declares.
  • Metadata objects are merged shallowly per field across nested layouts and pages: a page that defines its own alternates.languages replaces the parent's set entirely rather than adding to it.
 
Official sources
 
 
Shopify
 
Status: supported · Location: Shopify Markets configuration, or the layout/theme.liquid content_for_header output for Markets-driven storefronts
 
Steps
  1. Confirm the storefront uses Shopify Markets: Shopify automatically adds hreflang tags built from each market's configured languages and regions via content_for_header, and keeps them in sync with each page's own canonical URL and with market changes.
  2. If the Markets configuration is missing a language, region, or domain that should be in the cluster, add it in Markets rather than hand-editing hreflang output — the automatic tags are generated from that configuration.
  3. If hreflang is emitted manually instead of through content_for_header, build the tag set dynamically from the localization object rather than hardcoding domains or resource handles, because a handle can differ per language and the head partial renders on every page.
  4. Either way, confirm each localized URL still references itself as its own canonical URL — Shopify's guidance calls this out as a prerequisite for the automatic tags to behave correctly.
  
Verify on this platform
 
  • View source on a representative page in each market/language and confirm the emitted hreflang set is complete and reciprocal, then confirm each localized URL's own canonical tag matches its own URL.
 
Rollback
  1. Revert the Markets configuration change or the manual theme edit if it drops a market or language still needed, then re-diagnose the true cluster membership before republishing.
 
Caveats
  • This applies to Shopify Markets storefronts on Online Store themes using the standard content_for_header output; a storefront that overrides this partial, uses Hydrogen, or manages locales outside Markets is not covered — verify that system's own workflow instead.
  • Shopify's own hreflang documentation does not address x-default; do not assume Shopify emits one automatically.
 
Official sources
 
 
Platform-managed / ask the vendor
 
Status: platform-managed · Location: Vendor-owned page builder, headless frontend, or hosted platform template
 
Implementation is controlled by the platform or vendor.
  
Verify on this platform
 
  • Ask the vendor to confirm which single layer emits hreflang for the cluster and how cluster membership is kept in sync across pages, then fetch every cluster member directly to confirm reciprocal, self-referencing, live-target hreflang.
  
Caveats
  • Escalate when the vendor cannot identify the layer emitting hreflang, cannot explain how it keeps membership in sync across pages, or when fetched pages keep disagreeing after every input you control has been made consistent.
  • Do not accept a claim that hreflang is correct without directly fetching each cluster member and each alternate target.
 
Official sources
 
 
 
 
 How to verify 
 
  1. Fetch every page believed to be in the cluster and record its complete hreflang set.
  2. Confirm the set is identical across every member, that every member lists itself, and that every pair is reciprocal.
  3. Confirm every declared alternate target returns a live 200 response without redirecting, and that its own canonical points to itself rather than elsewhere.
  4. Rerun the returntag - hreflang checker (and, for pages diagnosed via Raw vs. Rendered HTML Checker, confirm the same hreflang set survives rendering) on the same cluster.
 
Escalate when
 
Escalate when the system responsible for cluster membership cannot be identified, more than one system claims to manage hreflang for the same pages, or fetched pages keep disagreeing on membership after every input you control has been made consistent.
 
 
 
 
 
 
 
Raw vs. Rendered HTML Checker · one finding
 
Critical content depends on client rendering
 
Recommended action: Server-render or prerender the title, H1, links, and primary content in the initial HTML.
 
Fix principle: Make critical content available in build-time or request-time server output; diagnose browser-only data paths rather than treating framework client-component syntax as proof that initial HTML is missing.
 
 
 
 Implementation for your setup 
 
Confirm first: View source lacks critical content that appears after rendering. A non-rendering fetch receives a shell or materially incomplete page. Critical content, a real navigable link, or the page's true destination or route only exists after a script runs — including content gated behind a click or scroll interaction, a client-side redirect, hash-only routing, or a connection type (such as WebSocket) Googlebot does not support.
 
Do not apply when: Critical content is already present in the initial HTML and only presentation is hydrated. The observed difference comes from personalization that is intentionally unavailable to crawlers. The content, link, or route is reachable without any click, scroll, or persistent client-side connection, and any redirect to it is a real HTTP or meta-refresh redirect rather than a JavaScript-only one.
 
Likely control points: cms-app · server · edge-cdn
 
   
Choose the layer that owns the final response.
 
 
 
Generic HTTP / HTML
 
Status: supported · Location: Build pipeline, application server, or origin templates
 
Steps
  1. Choose build-time prerendering for content known at release time or request-time server rendering for content needed per request.
  2. Render the critical title, heading, links, and main content into the response, then hydrate only the interactions that need a browser.
  3. Reveal important content in the DOM without requiring a click, tab switch, or scroll to trigger it — Google Search does not interact with the page, so use CSS or an interaction-independent method (for example IntersectionObserver-based lazy loading) instead of loading content only on user action.
  4. Replace a client-side-only redirect with a real server-side HTTP redirect (or, when that is not feasible, a meta refresh); use a JavaScript redirect only as a last resort, since a rendering failure can mean Google never observes it.
  5. Replace hash-only routes (for example /#/products) with real, individually navigable URLs served through the History API or server-side routing, so each state has its own crawlable address.
  6. If content depends on a WebSocket or WebRTC connection established client-side, provide an HTTP-reachable equivalent or fallback for that same critical content, since Googlebot only retrieves content over HTTP.
  
Verify on this platform
 
  • Fetch the final public response without executing JavaScript and compare its critical content with the rendered page and Search Console live test.
  • Confirm important content and primary navigation links are present in the rendered DOM without simulating a click, tab switch, or scroll, and that the page's real destination and individual routes resolve to distinct HTTP-fetchable URLs rather than only a hash fragment or a WebSocket-delivered update.
 
Rollback
  1. Restore the prior renderer, redirect method, or routing approach while retaining the confirmed working response path if the change breaks user functionality.
 
Caveats
  • Do not default to user-agent-based dynamic rendering; Google describes it as a workaround rather than a recommended long-term solution.
  • Trace data loaded only in effects, browser-only APIs, disabled SSR, or an app shell before changing the rendering architecture.
  • A rendered page that looks like a soft 404 is usually the same underlying defect at its most severe: confirm whether content is simply late, hidden behind interaction, or genuinely absent, and apply the matching step above rather than treating it as a distinct problem.
 
Official sources
 
 
Next.js / Vercel
 
Status: supported · Location: App Router Server/Client Component boundaries or Pages Router rendering method
 
Steps
  1. In the App Router, keep critical fetching and document content in server-rendered output; isolate only interactive code behind Client Component boundaries.
  2. In the Pages Router, use static generation or request-time server rendering for critical content instead of loading it only after mount.
  3. Remove an unintended dynamic import with ssr: false, useEffect-only fetch, browser-only guard, or app-shell dependency from the critical path.
  
Verify on this platform
 
  • Inspect the deployed response without executing JavaScript, then rerun Render Gap and the Search Console live test on the same production URL.
 
Rollback
  1. Revert the affected route or component boundary if the deployment causes a functional regression.
 
Caveats
  • A Next.js "use client" directive does not by itself mean missing initial HTML: Client Components are prerendered on the first load.
  • Skipping SSR with ssr: false is supported only for Client Components and can intentionally remove their server-rendered output.
  • A client-side router.push() redirect, hash-only route, or client-established WebSocket is a code-level defect independent of the App/Pages Router choice — apply the generic-http-html guidance above (server-side redirect, History-API routing, HTTP fallback) at the component that owns that behavior.
 
Official sources
 
 
Vue / Nuxt
 
Status: supported · Location: Nuxt route rendering and deployment preset
 
Steps
  1. For Nuxt 4, keep universal rendering enabled for the route or prerender the route when its content is known at build time.
  2. Deploy with the Nuxt preset that matches the real host and verify the server or static output is being served.
  3. For plain Vue, select and verify the actual SSR architecture and host before applying implementation steps.
  
Verify on this platform
 
  • Fetch the deployed route without browser execution and confirm the critical content exists in the response; then rerun Render Gap.
 
Rollback
  1. Restore the prior Nuxt route rule, prerender list, or deployment preset if the route regresses.
 
Caveats
  • Plain Vue implementation is not verified by this recipe unless the site’s real SSR setup and deployment host are identified.
  • Client-only data fetching can still create a gap even when the application uses an SSR-capable framework.
  • A router-only (hash mode) route, a client-side redirect, or a client-established WebSocket is a Vue Router or application-code defect independent of Nuxt's rendering mode — apply the generic-http-html guidance above at the component or router configuration that owns it.
 
Official sources
 
 
WordPress
 
Status: supported · Location: Native classic/block theme template and post-content output
 
Steps
  1. For a classic theme, render the intended entry content through the selected template and the_content().
  2. For a block theme, keep the Post Content block in the applicable template and verify the template hierarchy selects it.
  
Verify on this platform
 
  • View the logged-out public response and confirm the native template emits the critical content before browser scripts run.
 
Rollback
  1. Restore the prior native template or template part if the published layout or content regresses.
 
Caveats
  • These steps cover native classic and block themes only.
  • A page builder or headless WordPress frontend is owner-managed; use that rendering system’s verified workflow instead of assuming core theme controls own the output.
  • Content gated behind a click/tab/accordion, a JavaScript-only redirect, or hash-only navigation added by a theme or plugin script is a separate defect from template output — apply the generic-http-html guidance above at the script that owns that behavior.
 
Official sources
 
 
Shopify
 
Status: supported · Location: Online Store Liquid or JSON theme templates
 
Steps
  1. Duplicate the active theme and make the rendering correction in the duplicate Liquid or JSON template.
  2. Preview representative product, collection, and content routes before publishing the corrected theme.
  
Verify on this platform
 
  • Inspect the preview and then published storefront response without browser execution and confirm the critical content is present.
 
Rollback
  1. Republish the previous theme if the new theme regresses storefront content or functionality.
 
Caveats
  • These steps apply only to Shopify Online Store Liquid/JSON themes.
  • An app-owned storefront or Hydrogen implementation is owner-managed and needs its own verified rendering workflow.
  • Content gated behind a click/tab, a JavaScript-only redirect, or hash-only navigation added by a theme script or app embed is a separate defect from template output — apply the generic-http-html guidance above at the script that owns that behavior.
 
Official sources
 
 
Platform-managed / ask the vendor
 
Status: platform-managed · Location: Vendor-owned renderer, page builder, or hosted storefront
 
Implementation is controlled by the platform or vendor.
  
Verify on this platform
 
  • Ask the vendor to demonstrate the uncached initial HTML returned to crawlers and users.
  
Caveats
  • Escalate when the platform cannot expose or configure its rendering mode.
  • Require one production-URL response comparison rather than accepting a claim that the browser eventually renders the content.
  • Ask the vendor to confirm content is not gated behind interaction, redirects are not JavaScript-only, and routes are not hash-only.
 
Official sources
 
 
 
 
 How to verify 
 
  1. Fetch the public URL without JavaScript.
  2. Compare initial HTML and rendered DOM for the same title, H1, primary links, and content.
  3. Confirm important content and links are reachable without simulating a click, tab switch, or scroll, any redirect resolves at the HTTP or meta-refresh layer rather than only via JavaScript, and routes are individually fetchable rather than hash-only.
  4. Rerun Render Gap after deployment.
 
Escalate when
 
Escalate when the rendering layer is vendor-controlled, server rendering changes routing or authentication, or the raw and rendered views cannot be reproduced consistently.
 
 
 
 
 
 
 
Raw vs. Rendered HTML Checker · one finding
 
Important content appears only after rendering
 
Recommended action: Server-render or statically generate the important copy so it exists in the initial HTML.
 
Fix principle: Make critical content available in build-time or request-time server output; diagnose browser-only data paths rather than treating framework client-component syntax as proof that initial HTML is missing.
 
 
 
 Implementation for your setup 
 
Confirm first: View source lacks critical content that appears after rendering. A non-rendering fetch receives a shell or materially incomplete page. Critical content, a real navigable link, or the page's true destination or route only exists after a script runs — including content gated behind a click or scroll interaction, a client-side redirect, hash-only routing, or a connection type (such as WebSocket) Googlebot does not support.
 
Do not apply when: Critical content is already present in the initial HTML and only presentation is hydrated. The observed difference comes from personalization that is intentionally unavailable to crawlers. The content, link, or route is reachable without any click, scroll, or persistent client-side connection, and any redirect to it is a real HTTP or meta-refresh redirect rather than a JavaScript-only one.
 
Likely control points: cms-app · server · edge-cdn
 
   
Choose the layer that owns the final response.
 
 
 
Generic HTTP / HTML
 
Status: supported · Location: Build pipeline, application server, or origin templates
 
Steps
  1. Choose build-time prerendering for content known at release time or request-time server rendering for content needed per request.
  2. Render the critical title, heading, links, and main content into the response, then hydrate only the interactions that need a browser.
  3. Reveal important content in the DOM without requiring a click, tab switch, or scroll to trigger it — Google Search does not interact with the page, so use CSS or an interaction-independent method (for example IntersectionObserver-based lazy loading) instead of loading content only on user action.
  4. Replace a client-side-only redirect with a real server-side HTTP redirect (or, when that is not feasible, a meta refresh); use a JavaScript redirect only as a last resort, since a rendering failure can mean Google never observes it.
  5. Replace hash-only routes (for example /#/products) with real, individually navigable URLs served through the History API or server-side routing, so each state has its own crawlable address.
  6. If content depends on a WebSocket or WebRTC connection established client-side, provide an HTTP-reachable equivalent or fallback for that same critical content, since Googlebot only retrieves content over HTTP.
  
Verify on this platform
 
  • Fetch the final public response without executing JavaScript and compare its critical content with the rendered page and Search Console live test.
  • Confirm important content and primary navigation links are present in the rendered DOM without simulating a click, tab switch, or scroll, and that the page's real destination and individual routes resolve to distinct HTTP-fetchable URLs rather than only a hash fragment or a WebSocket-delivered update.
 
Rollback
  1. Restore the prior renderer, redirect method, or routing approach while retaining the confirmed working response path if the change breaks user functionality.
 
Caveats
  • Do not default to user-agent-based dynamic rendering; Google describes it as a workaround rather than a recommended long-term solution.
  • Trace data loaded only in effects, browser-only APIs, disabled SSR, or an app shell before changing the rendering architecture.
  • A rendered page that looks like a soft 404 is usually the same underlying defect at its most severe: confirm whether content is simply late, hidden behind interaction, or genuinely absent, and apply the matching step above rather than treating it as a distinct problem.
 
Official sources
 
 
Next.js / Vercel
 
Status: supported · Location: App Router Server/Client Component boundaries or Pages Router rendering method
 
Steps
  1. In the App Router, keep critical fetching and document content in server-rendered output; isolate only interactive code behind Client Component boundaries.
  2. In the Pages Router, use static generation or request-time server rendering for critical content instead of loading it only after mount.
  3. Remove an unintended dynamic import with ssr: false, useEffect-only fetch, browser-only guard, or app-shell dependency from the critical path.
  
Verify on this platform
 
  • Inspect the deployed response without executing JavaScript, then rerun Render Gap and the Search Console live test on the same production URL.
 
Rollback
  1. Revert the affected route or component boundary if the deployment causes a functional regression.
 
Caveats
  • A Next.js "use client" directive does not by itself mean missing initial HTML: Client Components are prerendered on the first load.
  • Skipping SSR with ssr: false is supported only for Client Components and can intentionally remove their server-rendered output.
  • A client-side router.push() redirect, hash-only route, or client-established WebSocket is a code-level defect independent of the App/Pages Router choice — apply the generic-http-html guidance above (server-side redirect, History-API routing, HTTP fallback) at the component that owns that behavior.
 
Official sources
 
 
Vue / Nuxt
 
Status: supported · Location: Nuxt route rendering and deployment preset
 
Steps
  1. For Nuxt 4, keep universal rendering enabled for the route or prerender the route when its content is known at build time.
  2. Deploy with the Nuxt preset that matches the real host and verify the server or static output is being served.
  3. For plain Vue, select and verify the actual SSR architecture and host before applying implementation steps.
  
Verify on this platform
 
  • Fetch the deployed route without browser execution and confirm the critical content exists in the response; then rerun Render Gap.
 
Rollback
  1. Restore the prior Nuxt route rule, prerender list, or deployment preset if the route regresses.
 
Caveats
  • Plain Vue implementation is not verified by this recipe unless the site’s real SSR setup and deployment host are identified.
  • Client-only data fetching can still create a gap even when the application uses an SSR-capable framework.
  • A router-only (hash mode) route, a client-side redirect, or a client-established WebSocket is a Vue Router or application-code defect independent of Nuxt's rendering mode — apply the generic-http-html guidance above at the component or router configuration that owns it.
 
Official sources
 
 
WordPress
 
Status: supported · Location: Native classic/block theme template and post-content output
 
Steps
  1. For a classic theme, render the intended entry content through the selected template and the_content().
  2. For a block theme, keep the Post Content block in the applicable template and verify the template hierarchy selects it.
  
Verify on this platform
 
  • View the logged-out public response and confirm the native template emits the critical content before browser scripts run.
 
Rollback
  1. Restore the prior native template or template part if the published layout or content regresses.
 
Caveats
  • These steps cover native classic and block themes only.
  • A page builder or headless WordPress frontend is owner-managed; use that rendering system’s verified workflow instead of assuming core theme controls own the output.
  • Content gated behind a click/tab/accordion, a JavaScript-only redirect, or hash-only navigation added by a theme or plugin script is a separate defect from template output — apply the generic-http-html guidance above at the script that owns that behavior.
 
Official sources
 
 
Shopify
 
Status: supported · Location: Online Store Liquid or JSON theme templates
 
Steps
  1. Duplicate the active theme and make the rendering correction in the duplicate Liquid or JSON template.
  2. Preview representative product, collection, and content routes before publishing the corrected theme.
  
Verify on this platform
 
  • Inspect the preview and then published storefront response without browser execution and confirm the critical content is present.
 
Rollback
  1. Republish the previous theme if the new theme regresses storefront content or functionality.
 
Caveats
  • These steps apply only to Shopify Online Store Liquid/JSON themes.
  • An app-owned storefront or Hydrogen implementation is owner-managed and needs its own verified rendering workflow.
  • Content gated behind a click/tab, a JavaScript-only redirect, or hash-only navigation added by a theme script or app embed is a separate defect from template output — apply the generic-http-html guidance above at the script that owns that behavior.
 
Official sources
 
 
Platform-managed / ask the vendor
 
Status: platform-managed · Location: Vendor-owned renderer, page builder, or hosted storefront
 
Implementation is controlled by the platform or vendor.
  
Verify on this platform
 
  • Ask the vendor to demonstrate the uncached initial HTML returned to crawlers and users.
  
Caveats
  • Escalate when the platform cannot expose or configure its rendering mode.
  • Require one production-URL response comparison rather than accepting a claim that the browser eventually renders the content.
  • Ask the vendor to confirm content is not gated behind interaction, redirects are not JavaScript-only, and routes are not hash-only.
 
Official sources
 
 
 
 
 How to verify 
 
  1. Fetch the public URL without JavaScript.
  2. Compare initial HTML and rendered DOM for the same title, H1, primary links, and content.
  3. Confirm important content and links are reachable without simulating a click, tab switch, or scroll, any redirect resolves at the HTTP or meta-refresh layer rather than only via JavaScript, and routes are individually fetchable rather than hash-only.
  4. Rerun Render Gap after deployment.
 
Escalate when
 
Escalate when the rendering layer is vendor-controlled, server rendering changes routing or authentication, or the raw and rendered views cannot be reproduced consistently.
 
 
 
 
 
 
 
Raw vs. Rendered HTML Checker · one finding
 
Substantial content is added after rendering
 
Recommended action: Move the essential JavaScript-added copy into initial HTML and leave only nonessential enhancements to the client.
 
Fix principle: Make critical content available in build-time or request-time server output; diagnose browser-only data paths rather than treating framework client-component syntax as proof that initial HTML is missing.
 
 
 
 Implementation for your setup 
 
Confirm first: View source lacks critical content that appears after rendering. A non-rendering fetch receives a shell or materially incomplete page. Critical content, a real navigable link, or the page's true destination or route only exists after a script runs — including content gated behind a click or scroll interaction, a client-side redirect, hash-only routing, or a connection type (such as WebSocket) Googlebot does not support.
 
Do not apply when: Critical content is already present in the initial HTML and only presentation is hydrated. The observed difference comes from personalization that is intentionally unavailable to crawlers. The content, link, or route is reachable without any click, scroll, or persistent client-side connection, and any redirect to it is a real HTTP or meta-refresh redirect rather than a JavaScript-only one.
 
Likely control points: cms-app · server · edge-cdn
 
   
Choose the layer that owns the final response.
 
 
 
Generic HTTP / HTML
 
Status: supported · Location: Build pipeline, application server, or origin templates
 
Steps
  1. Choose build-time prerendering for content known at release time or request-time server rendering for content needed per request.
  2. Render the critical title, heading, links, and main content into the response, then hydrate only the interactions that need a browser.
  3. Reveal important content in the DOM without requiring a click, tab switch, or scroll to trigger it — Google Search does not interact with the page, so use CSS or an interaction-independent method (for example IntersectionObserver-based lazy loading) instead of loading content only on user action.
  4. Replace a client-side-only redirect with a real server-side HTTP redirect (or, when that is not feasible, a meta refresh); use a JavaScript redirect only as a last resort, since a rendering failure can mean Google never observes it.
  5. Replace hash-only routes (for example /#/products) with real, individually navigable URLs served through the History API or server-side routing, so each state has its own crawlable address.
  6. If content depends on a WebSocket or WebRTC connection established client-side, provide an HTTP-reachable equivalent or fallback for that same critical content, since Googlebot only retrieves content over HTTP.
  
Verify on this platform
 
  • Fetch the final public response without executing JavaScript and compare its critical content with the rendered page and Search Console live test.
  • Confirm important content and primary navigation links are present in the rendered DOM without simulating a click, tab switch, or scroll, and that the page's real destination and individual routes resolve to distinct HTTP-fetchable URLs rather than only a hash fragment or a WebSocket-delivered update.
 
Rollback
  1. Restore the prior renderer, redirect method, or routing approach while retaining the confirmed working response path if the change breaks user functionality.
 
Caveats
  • Do not default to user-agent-based dynamic rendering; Google describes it as a workaround rather than a recommended long-term solution.
  • Trace data loaded only in effects, browser-only APIs, disabled SSR, or an app shell before changing the rendering architecture.
  • A rendered page that looks like a soft 404 is usually the same underlying defect at its most severe: confirm whether content is simply late, hidden behind interaction, or genuinely absent, and apply the matching step above rather than treating it as a distinct problem.
 
Official sources
 
 
Next.js / Vercel
 
Status: supported · Location: App Router Server/Client Component boundaries or Pages Router rendering method
 
Steps
  1. In the App Router, keep critical fetching and document content in server-rendered output; isolate only interactive code behind Client Component boundaries.
  2. In the Pages Router, use static generation or request-time server rendering for critical content instead of loading it only after mount.
  3. Remove an unintended dynamic import with ssr: false, useEffect-only fetch, browser-only guard, or app-shell dependency from the critical path.
  
Verify on this platform
 
  • Inspect the deployed response without executing JavaScript, then rerun Render Gap and the Search Console live test on the same production URL.
 
Rollback
  1. Revert the affected route or component boundary if the deployment causes a functional regression.
 
Caveats
  • A Next.js "use client" directive does not by itself mean missing initial HTML: Client Components are prerendered on the first load.
  • Skipping SSR with ssr: false is supported only for Client Components and can intentionally remove their server-rendered output.
  • A client-side router.push() redirect, hash-only route, or client-established WebSocket is a code-level defect independent of the App/Pages Router choice — apply the generic-http-html guidance above (server-side redirect, History-API routing, HTTP fallback) at the component that owns that behavior.
 
Official sources
 
 
Vue / Nuxt
 
Status: supported · Location: Nuxt route rendering and deployment preset
 
Steps
  1. For Nuxt 4, keep universal rendering enabled for the route or prerender the route when its content is known at build time.
  2. Deploy with the Nuxt preset that matches the real host and verify the server or static output is being served.
  3. For plain Vue, select and verify the actual SSR architecture and host before applying implementation steps.
  
Verify on this platform
 
  • Fetch the deployed route without browser execution and confirm the critical content exists in the response; then rerun Render Gap.
 
Rollback
  1. Restore the prior Nuxt route rule, prerender list, or deployment preset if the route regresses.
 
Caveats
  • Plain Vue implementation is not verified by this recipe unless the site’s real SSR setup and deployment host are identified.
  • Client-only data fetching can still create a gap even when the application uses an SSR-capable framework.
  • A router-only (hash mode) route, a client-side redirect, or a client-established WebSocket is a Vue Router or application-code defect independent of Nuxt's rendering mode — apply the generic-http-html guidance above at the component or router configuration that owns it.
 
Official sources
 
 
WordPress
 
Status: supported · Location: Native classic/block theme template and post-content output
 
Steps
  1. For a classic theme, render the intended entry content through the selected template and the_content().
  2. For a block theme, keep the Post Content block in the applicable template and verify the template hierarchy selects it.
  
Verify on this platform
 
  • View the logged-out public response and confirm the native template emits the critical content before browser scripts run.
 
Rollback
  1. Restore the prior native template or template part if the published layout or content regresses.
 
Caveats
  • These steps cover native classic and block themes only.
  • A page builder or headless WordPress frontend is owner-managed; use that rendering system’s verified workflow instead of assuming core theme controls own the output.
  • Content gated behind a click/tab/accordion, a JavaScript-only redirect, or hash-only navigation added by a theme or plugin script is a separate defect from template output — apply the generic-http-html guidance above at the script that owns that behavior.
 
Official sources
 
 
Shopify
 
Status: supported · Location: Online Store Liquid or JSON theme templates
 
Steps
  1. Duplicate the active theme and make the rendering correction in the duplicate Liquid or JSON template.
  2. Preview representative product, collection, and content routes before publishing the corrected theme.
  
Verify on this platform
 
  • Inspect the preview and then published storefront response without browser execution and confirm the critical content is present.
 
Rollback
  1. Republish the previous theme if the new theme regresses storefront content or functionality.
 
Caveats
  • These steps apply only to Shopify Online Store Liquid/JSON themes.
  • An app-owned storefront or Hydrogen implementation is owner-managed and needs its own verified rendering workflow.
  • Content gated behind a click/tab, a JavaScript-only redirect, or hash-only navigation added by a theme script or app embed is a separate defect from template output — apply the generic-http-html guidance above at the script that owns that behavior.
 
Official sources
 
 
Platform-managed / ask the vendor
 
Status: platform-managed · Location: Vendor-owned renderer, page builder, or hosted storefront
 
Implementation is controlled by the platform or vendor.
  
Verify on this platform
 
  • Ask the vendor to demonstrate the uncached initial HTML returned to crawlers and users.
  
Caveats
  • Escalate when the platform cannot expose or configure its rendering mode.
  • Require one production-URL response comparison rather than accepting a claim that the browser eventually renders the content.
  • Ask the vendor to confirm content is not gated behind interaction, redirects are not JavaScript-only, and routes are not hash-only.
 
Official sources
 
 
 
 
 How to verify 
 
  1. Fetch the public URL without JavaScript.
  2. Compare initial HTML and rendered DOM for the same title, H1, primary links, and content.
  3. Confirm important content and links are reachable without simulating a click, tab switch, or scroll, any redirect resolves at the HTTP or meta-refresh layer rather than only via JavaScript, and routes are individually fetchable rather than hash-only.
  4. Rerun Render Gap after deployment.
 
Escalate when
 
Escalate when the rendering layer is vendor-controlled, server rendering changes routing or authentication, or the raw and rendered views cannot be reproduced consistently.
 
 
 
 
  
 
 
Raw vs. Rendered HTML Checker · one finding
 
Important content is hidden in the rendered DOM
 
Recommended action: Make the important DOM content visibly available by default or through an accessible expandable control.
 
Fix principle: Make critical content available in build-time or request-time server output; diagnose browser-only data paths rather than treating framework client-component syntax as proof that initial HTML is missing.
 
 
 
 Implementation for your setup 
 
Confirm first: View source lacks critical content that appears after rendering. A non-rendering fetch receives a shell or materially incomplete page. Critical content, a real navigable link, or the page's true destination or route only exists after a script runs — including content gated behind a click or scroll interaction, a client-side redirect, hash-only routing, or a connection type (such as WebSocket) Googlebot does not support.
 
Do not apply when: Critical content is already present in the initial HTML and only presentation is hydrated. The observed difference comes from personalization that is intentionally unavailable to crawlers. The content, link, or route is reachable without any click, scroll, or persistent client-side connection, and any redirect to it is a real HTTP or meta-refresh redirect rather than a JavaScript-only one.
 
Likely control points: cms-app · server · edge-cdn
 
   
Choose the layer that owns the final response.
 
 
 
Generic HTTP / HTML
 
Status: supported · Location: Build pipeline, application server, or origin templates
 
Steps
  1. Choose build-time prerendering for content known at release time or request-time server rendering for content needed per request.
  2. Render the critical title, heading, links, and main content into the response, then hydrate only the interactions that need a browser.
  3. Reveal important content in the DOM without requiring a click, tab switch, or scroll to trigger it — Google Search does not interact with the page, so use CSS or an interaction-independent method (for example IntersectionObserver-based lazy loading) instead of loading content only on user action.
  4. Replace a client-side-only redirect with a real server-side HTTP redirect (or, when that is not feasible, a meta refresh); use a JavaScript redirect only as a last resort, since a rendering failure can mean Google never observes it.
  5. Replace hash-only routes (for example /#/products) with real, individually navigable URLs served through the History API or server-side routing, so each state has its own crawlable address.
  6. If content depends on a WebSocket or WebRTC connection established client-side, provide an HTTP-reachable equivalent or fallback for that same critical content, since Googlebot only retrieves content over HTTP.
  
Verify on this platform
 
  • Fetch the final public response without executing JavaScript and compare its critical content with the rendered page and Search Console live test.
  • Confirm important content and primary navigation links are present in the rendered DOM without simulating a click, tab switch, or scroll, and that the page's real destination and individual routes resolve to distinct HTTP-fetchable URLs rather than only a hash fragment or a WebSocket-delivered update.
 
Rollback
  1. Restore the prior renderer, redirect method, or routing approach while retaining the confirmed working response path if the change breaks user functionality.
 
Caveats
  • Do not default to user-agent-based dynamic rendering; Google describes it as a workaround rather than a recommended long-term solution.
  • Trace data loaded only in effects, browser-only APIs, disabled SSR, or an app shell before changing the rendering architecture.
  • A rendered page that looks like a soft 404 is usually the same underlying defect at its most severe: confirm whether content is simply late, hidden behind interaction, or genuinely absent, and apply the matching step above rather than treating it as a distinct problem.
 
Official sources
 
 
Next.js / Vercel
 
Status: supported · Location: App Router Server/Client Component boundaries or Pages Router rendering method
 
Steps
  1. In the App Router, keep critical fetching and document content in server-rendered output; isolate only interactive code behind Client Component boundaries.
  2. In the Pages Router, use static generation or request-time server rendering for critical content instead of loading it only after mount.
  3. Remove an unintended dynamic import with ssr: false, useEffect-only fetch, browser-only guard, or app-shell dependency from the critical path.
  
Verify on this platform
 
  • Inspect the deployed response without executing JavaScript, then rerun Render Gap and the Search Console live test on the same production URL.
 
Rollback
  1. Revert the affected route or component boundary if the deployment causes a functional regression.
 
Caveats
  • A Next.js "use client" directive does not by itself mean missing initial HTML: Client Components are prerendered on the first load.
  • Skipping SSR with ssr: false is supported only for Client Components and can intentionally remove their server-rendered output.
  • A client-side router.push() redirect, hash-only route, or client-established WebSocket is a code-level defect independent of the App/Pages Router choice — apply the generic-http-html guidance above (server-side redirect, History-API routing, HTTP fallback) at the component that owns that behavior.
 
Official sources
 
 
Vue / Nuxt
 
Status: supported · Location: Nuxt route rendering and deployment preset
 
Steps
  1. For Nuxt 4, keep universal rendering enabled for the route or prerender the route when its content is known at build time.
  2. Deploy with the Nuxt preset that matches the real host and verify the server or static output is being served.
  3. For plain Vue, select and verify the actual SSR architecture and host before applying implementation steps.
  
Verify on this platform
 
  • Fetch the deployed route without browser execution and confirm the critical content exists in the response; then rerun Render Gap.
 
Rollback
  1. Restore the prior Nuxt route rule, prerender list, or deployment preset if the route regresses.
 
Caveats
  • Plain Vue implementation is not verified by this recipe unless the site’s real SSR setup and deployment host are identified.
  • Client-only data fetching can still create a gap even when the application uses an SSR-capable framework.
  • A router-only (hash mode) route, a client-side redirect, or a client-established WebSocket is a Vue Router or application-code defect independent of Nuxt's rendering mode — apply the generic-http-html guidance above at the component or router configuration that owns it.
 
Official sources
 
 
WordPress
 
Status: supported · Location: Native classic/block theme template and post-content output
 
Steps
  1. For a classic theme, render the intended entry content through the selected template and the_content().
  2. For a block theme, keep the Post Content block in the applicable template and verify the template hierarchy selects it.
  
Verify on this platform
 
  • View the logged-out public response and confirm the native template emits the critical content before browser scripts run.
 
Rollback
  1. Restore the prior native template or template part if the published layout or content regresses.
 
Caveats
  • These steps cover native classic and block themes only.
  • A page builder or headless WordPress frontend is owner-managed; use that rendering system’s verified workflow instead of assuming core theme controls own the output.
  • Content gated behind a click/tab/accordion, a JavaScript-only redirect, or hash-only navigation added by a theme or plugin script is a separate defect from template output — apply the generic-http-html guidance above at the script that owns that behavior.
 
Official sources
 
 
Shopify
 
Status: supported · Location: Online Store Liquid or JSON theme templates
 
Steps
  1. Duplicate the active theme and make the rendering correction in the duplicate Liquid or JSON template.
  2. Preview representative product, collection, and content routes before publishing the corrected theme.
  
Verify on this platform
 
  • Inspect the preview and then published storefront response without browser execution and confirm the critical content is present.
 
Rollback
  1. Republish the previous theme if the new theme regresses storefront content or functionality.
 
Caveats
  • These steps apply only to Shopify Online Store Liquid/JSON themes.
  • An app-owned storefront or Hydrogen implementation is owner-managed and needs its own verified rendering workflow.
  • Content gated behind a click/tab, a JavaScript-only redirect, or hash-only navigation added by a theme script or app embed is a separate defect from template output — apply the generic-http-html guidance above at the script that owns that behavior.
 
Official sources
 
 
Platform-managed / ask the vendor
 
Status: platform-managed · Location: Vendor-owned renderer, page builder, or hosted storefront
 
Implementation is controlled by the platform or vendor.
  
Verify on this platform
 
  • Ask the vendor to demonstrate the uncached initial HTML returned to crawlers and users.
  
Caveats
  • Escalate when the platform cannot expose or configure its rendering mode.
  • Require one production-URL response comparison rather than accepting a claim that the browser eventually renders the content.
  • Ask the vendor to confirm content is not gated behind interaction, redirects are not JavaScript-only, and routes are not hash-only.
 
Official sources
 
 
 
 
 How to verify 
 
  1. Fetch the public URL without JavaScript.
  2. Compare initial HTML and rendered DOM for the same title, H1, primary links, and content.
  3. Confirm important content and links are reachable without simulating a click, tab switch, or scroll, any redirect resolves at the HTTP or meta-refresh layer rather than only via JavaScript, and routes are individually fetchable rather than hash-only.
  4. Rerun Render Gap after deployment.
 
Escalate when
 
Escalate when the rendering layer is vendor-controlled, server rendering changes routing or authentication, or the raw and rendered views cannot be reproduced consistently.
 
 
 
 
 
 
 
Raw vs. Rendered HTML Checker · one finding
 
Important content requires interaction
 
Recommended action: Put the full content in the loaded DOM or give it a crawlable URL instead of requiring a click or scroll.
 
Fix principle: Make critical content available in build-time or request-time server output; diagnose browser-only data paths rather than treating framework client-component syntax as proof that initial HTML is missing.
 
 
 
 Implementation for your setup 
 
Confirm first: View source lacks critical content that appears after rendering. A non-rendering fetch receives a shell or materially incomplete page. Critical content, a real navigable link, or the page's true destination or route only exists after a script runs — including content gated behind a click or scroll interaction, a client-side redirect, hash-only routing, or a connection type (such as WebSocket) Googlebot does not support.
 
Do not apply when: Critical content is already present in the initial HTML and only presentation is hydrated. The observed difference comes from personalization that is intentionally unavailable to crawlers. The content, link, or route is reachable without any click, scroll, or persistent client-side connection, and any redirect to it is a real HTTP or meta-refresh redirect rather than a JavaScript-only one.
 
Likely control points: cms-app · server · edge-cdn
 
   
Choose the layer that owns the final response.
 
 
 
Generic HTTP / HTML
 
Status: supported · Location: Build pipeline, application server, or origin templates
 
Steps
  1. Choose build-time prerendering for content known at release time or request-time server rendering for content needed per request.
  2. Render the critical title, heading, links, and main content into the response, then hydrate only the interactions that need a browser.
  3. Reveal important content in the DOM without requiring a click, tab switch, or scroll to trigger it — Google Search does not interact with the page, so use CSS or an interaction-independent method (for example IntersectionObserver-based lazy loading) instead of loading content only on user action.
  4. Replace a client-side-only redirect with a real server-side HTTP redirect (or, when that is not feasible, a meta refresh); use a JavaScript redirect only as a last resort, since a rendering failure can mean Google never observes it.
  5. Replace hash-only routes (for example /#/products) with real, individually navigable URLs served through the History API or server-side routing, so each state has its own crawlable address.
  6. If content depends on a WebSocket or WebRTC connection established client-side, provide an HTTP-reachable equivalent or fallback for that same critical content, since Googlebot only retrieves content over HTTP.
  
Verify on this platform
 
  • Fetch the final public response without executing JavaScript and compare its critical content with the rendered page and Search Console live test.
  • Confirm important content and primary navigation links are present in the rendered DOM without simulating a click, tab switch, or scroll, and that the page's real destination and individual routes resolve to distinct HTTP-fetchable URLs rather than only a hash fragment or a WebSocket-delivered update.
 
Rollback
  1. Restore the prior renderer, redirect method, or routing approach while retaining the confirmed working response path if the change breaks user functionality.
 
Caveats
  • Do not default to user-agent-based dynamic rendering; Google describes it as a workaround rather than a recommended long-term solution.
  • Trace data loaded only in effects, browser-only APIs, disabled SSR, or an app shell before changing the rendering architecture.
  • A rendered page that looks like a soft 404 is usually the same underlying defect at its most severe: confirm whether content is simply late, hidden behind interaction, or genuinely absent, and apply the matching step above rather than treating it as a distinct problem.
 
Official sources
 
 
Next.js / Vercel
 
Status: supported · Location: App Router Server/Client Component boundaries or Pages Router rendering method
 
Steps
  1. In the App Router, keep critical fetching and document content in server-rendered output; isolate only interactive code behind Client Component boundaries.
  2. In the Pages Router, use static generation or request-time server rendering for critical content instead of loading it only after mount.
  3. Remove an unintended dynamic import with ssr: false, useEffect-only fetch, browser-only guard, or app-shell dependency from the critical path.
  
Verify on this platform
 
  • Inspect the deployed response without executing JavaScript, then rerun Render Gap and the Search Console live test on the same production URL.
 
Rollback
  1. Revert the affected route or component boundary if the deployment causes a functional regression.
 
Caveats
  • A Next.js "use client" directive does not by itself mean missing initial HTML: Client Components are prerendered on the first load.
  • Skipping SSR with ssr: false is supported only for Client Components and can intentionally remove their server-rendered output.
  • A client-side router.push() redirect, hash-only route, or client-established WebSocket is a code-level defect independent of the App/Pages Router choice — apply the generic-http-html guidance above (server-side redirect, History-API routing, HTTP fallback) at the component that owns that behavior.
 
Official sources
 
 
Vue / Nuxt
 
Status: supported · Location: Nuxt route rendering and deployment preset
 
Steps
  1. For Nuxt 4, keep universal rendering enabled for the route or prerender the route when its content is known at build time.
  2. Deploy with the Nuxt preset that matches the real host and verify the server or static output is being served.
  3. For plain Vue, select and verify the actual SSR architecture and host before applying implementation steps.
  
Verify on this platform
 
  • Fetch the deployed route without browser execution and confirm the critical content exists in the response; then rerun Render Gap.
 
Rollback
  1. Restore the prior Nuxt route rule, prerender list, or deployment preset if the route regresses.
 
Caveats
  • Plain Vue implementation is not verified by this recipe unless the site’s real SSR setup and deployment host are identified.
  • Client-only data fetching can still create a gap even when the application uses an SSR-capable framework.
  • A router-only (hash mode) route, a client-side redirect, or a client-established WebSocket is a Vue Router or application-code defect independent of Nuxt's rendering mode — apply the generic-http-html guidance above at the component or router configuration that owns it.
 
Official sources
 
 
WordPress
 
Status: supported · Location: Native classic/block theme template and post-content output
 
Steps
  1. For a classic theme, render the intended entry content through the selected template and the_content().
  2. For a block theme, keep the Post Content block in the applicable template and verify the template hierarchy selects it.
  
Verify on this platform
 
  • View the logged-out public response and confirm the native template emits the critical content before browser scripts run.
 
Rollback
  1. Restore the prior native template or template part if the published layout or content regresses.
 
Caveats
  • These steps cover native classic and block themes only.
  • A page builder or headless WordPress frontend is owner-managed; use that rendering system’s verified workflow instead of assuming core theme controls own the output.
  • Content gated behind a click/tab/accordion, a JavaScript-only redirect, or hash-only navigation added by a theme or plugin script is a separate defect from template output — apply the generic-http-html guidance above at the script that owns that behavior.
 
Official sources
 
 
Shopify
 
Status: supported · Location: Online Store Liquid or JSON theme templates
 
Steps
  1. Duplicate the active theme and make the rendering correction in the duplicate Liquid or JSON template.
  2. Preview representative product, collection, and content routes before publishing the corrected theme.
  
Verify on this platform
 
  • Inspect the preview and then published storefront response without browser execution and confirm the critical content is present.
 
Rollback
  1. Republish the previous theme if the new theme regresses storefront content or functionality.
 
Caveats
  • These steps apply only to Shopify Online Store Liquid/JSON themes.
  • An app-owned storefront or Hydrogen implementation is owner-managed and needs its own verified rendering workflow.
  • Content gated behind a click/tab, a JavaScript-only redirect, or hash-only navigation added by a theme script or app embed is a separate defect from template output — apply the generic-http-html guidance above at the script that owns that behavior.
 
Official sources
 
 
Platform-managed / ask the vendor
 
Status: platform-managed · Location: Vendor-owned renderer, page builder, or hosted storefront
 
Implementation is controlled by the platform or vendor.
  
Verify on this platform
 
  • Ask the vendor to demonstrate the uncached initial HTML returned to crawlers and users.
  
Caveats
  • Escalate when the platform cannot expose or configure its rendering mode.
  • Require one production-URL response comparison rather than accepting a claim that the browser eventually renders the content.
  • Ask the vendor to confirm content is not gated behind interaction, redirects are not JavaScript-only, and routes are not hash-only.
 
Official sources
 
 
 
 
 How to verify 
 
  1. Fetch the public URL without JavaScript.
  2. Compare initial HTML and rendered DOM for the same title, H1, primary links, and content.
  3. Confirm important content and links are reachable without simulating a click, tab switch, or scroll, any redirect resolves at the HTTP or meta-refresh layer rather than only via JavaScript, and routes are individually fetchable rather than hash-only.
  4. Rerun Render Gap after deployment.
 
Escalate when
 
Escalate when the rendering layer is vendor-controlled, server rendering changes routing or authentication, or the raw and rendered views cannot be reproduced consistently.
 
 
 
 
 
 
 
Raw vs. Rendered HTML Checker · one finding
 
Rendered page looks like a soft 404
 
Recommended action: Return 404/410 for a missing page, or replace the thin error-like body with substantive content at the 200 URL.
 
Fix principle: Make critical content available in build-time or request-time server output; diagnose browser-only data paths rather than treating framework client-component syntax as proof that initial HTML is missing.
 
 
 
 Implementation for your setup 
 
Confirm first: View source lacks critical content that appears after rendering. A non-rendering fetch receives a shell or materially incomplete page. Critical content, a real navigable link, or the page's true destination or route only exists after a script runs — including content gated behind a click or scroll interaction, a client-side redirect, hash-only routing, or a connection type (such as WebSocket) Googlebot does not support.
 
Do not apply when: Critical content is already present in the initial HTML and only presentation is hydrated. The observed difference comes from personalization that is intentionally unavailable to crawlers. The content, link, or route is reachable without any click, scroll, or persistent client-side connection, and any redirect to it is a real HTTP or meta-refresh redirect rather than a JavaScript-only one.
 
Likely control points: cms-app · server · edge-cdn
 
   
Choose the layer that owns the final response.
 
 
 
Generic HTTP / HTML
 
Status: supported · Location: Build pipeline, application server, or origin templates
 
Steps
  1. Choose build-time prerendering for content known at release time or request-time server rendering for content needed per request.
  2. Render the critical title, heading, links, and main content into the response, then hydrate only the interactions that need a browser.
  3. Reveal important content in the DOM without requiring a click, tab switch, or scroll to trigger it — Google Search does not interact with the page, so use CSS or an interaction-independent method (for example IntersectionObserver-based lazy loading) instead of loading content only on user action.
  4. Replace a client-side-only redirect with a real server-side HTTP redirect (or, when that is not feasible, a meta refresh); use a JavaScript redirect only as a last resort, since a rendering failure can mean Google never observes it.
  5. Replace hash-only routes (for example /#/products) with real, individually navigable URLs served through the History API or server-side routing, so each state has its own crawlable address.
  6. If content depends on a WebSocket or WebRTC connection established client-side, provide an HTTP-reachable equivalent or fallback for that same critical content, since Googlebot only retrieves content over HTTP.
  
Verify on this platform
 
  • Fetch the final public response without executing JavaScript and compare its critical content with the rendered page and Search Console live test.
  • Confirm important content and primary navigation links are present in the rendered DOM without simulating a click, tab switch, or scroll, and that the page's real destination and individual routes resolve to distinct HTTP-fetchable URLs rather than only a hash fragment or a WebSocket-delivered update.
 
Rollback
  1. Restore the prior renderer, redirect method, or routing approach while retaining the confirmed working response path if the change breaks user functionality.
 
Caveats
  • Do not default to user-agent-based dynamic rendering; Google describes it as a workaround rather than a recommended long-term solution.
  • Trace data loaded only in effects, browser-only APIs, disabled SSR, or an app shell before changing the rendering architecture.
  • A rendered page that looks like a soft 404 is usually the same underlying defect at its most severe: confirm whether content is simply late, hidden behind interaction, or genuinely absent, and apply the matching step above rather than treating it as a distinct problem.
 
Official sources
 
 
Next.js / Vercel
 
Status: supported · Location: App Router Server/Client Component boundaries or Pages Router rendering method
 
Steps
  1. In the App Router, keep critical fetching and document content in server-rendered output; isolate only interactive code behind Client Component boundaries.
  2. In the Pages Router, use static generation or request-time server rendering for critical content instead of loading it only after mount.
  3. Remove an unintended dynamic import with ssr: false, useEffect-only fetch, browser-only guard, or app-shell dependency from the critical path.
  
Verify on this platform
 
  • Inspect the deployed response without executing JavaScript, then rerun Render Gap and the Search Console live test on the same production URL.
 
Rollback
  1. Revert the affected route or component boundary if the deployment causes a functional regression.
 
Caveats
  • A Next.js "use client" directive does not by itself mean missing initial HTML: Client Components are prerendered on the first load.
  • Skipping SSR with ssr: false is supported only for Client Components and can intentionally remove their server-rendered output.
  • A client-side router.push() redirect, hash-only route, or client-established WebSocket is a code-level defect independent of the App/Pages Router choice — apply the generic-http-html guidance above (server-side redirect, History-API routing, HTTP fallback) at the component that owns that behavior.
 
Official sources
 
 
Vue / Nuxt
 
Status: supported · Location: Nuxt route rendering and deployment preset
 
Steps
  1. For Nuxt 4, keep universal rendering enabled for the route or prerender the route when its content is known at build time.
  2. Deploy with the Nuxt preset that matches the real host and verify the server or static output is being served.
  3. For plain Vue, select and verify the actual SSR architecture and host before applying implementation steps.
  
Verify on this platform
 
  • Fetch the deployed route without browser execution and confirm the critical content exists in the response; then rerun Render Gap.
 
Rollback
  1. Restore the prior Nuxt route rule, prerender list, or deployment preset if the route regresses.
 
Caveats
  • Plain Vue implementation is not verified by this recipe unless the site’s real SSR setup and deployment host are identified.
  • Client-only data fetching can still create a gap even when the application uses an SSR-capable framework.
  • A router-only (hash mode) route, a client-side redirect, or a client-established WebSocket is a Vue Router or application-code defect independent of Nuxt's rendering mode — apply the generic-http-html guidance above at the component or router configuration that owns it.
 
Official sources
 
 
WordPress
 
Status: supported · Location: Native classic/block theme template and post-content output
 
Steps
  1. For a classic theme, render the intended entry content through the selected template and the_content().
  2. For a block theme, keep the Post Content block in the applicable template and verify the template hierarchy selects it.
  
Verify on this platform
 
  • View the logged-out public response and confirm the native template emits the critical content before browser scripts run.
 
Rollback
  1. Restore the prior native template or template part if the published layout or content regresses.
 
Caveats
  • These steps cover native classic and block themes only.
  • A page builder or headless WordPress frontend is owner-managed; use that rendering system’s verified workflow instead of assuming core theme controls own the output.
  • Content gated behind a click/tab/accordion, a JavaScript-only redirect, or hash-only navigation added by a theme or plugin script is a separate defect from template output — apply the generic-http-html guidance above at the script that owns that behavior.
 
Official sources
 
 
Shopify
 
Status: supported · Location: Online Store Liquid or JSON theme templates
 
Steps
  1. Duplicate the active theme and make the rendering correction in the duplicate Liquid or JSON template.
  2. Preview representative product, collection, and content routes before publishing the corrected theme.
  
Verify on this platform
 
  • Inspect the preview and then published storefront response without browser execution and confirm the critical content is present.
 
Rollback
  1. Republish the previous theme if the new theme regresses storefront content or functionality.
 
Caveats
  • These steps apply only to Shopify Online Store Liquid/JSON themes.
  • An app-owned storefront or Hydrogen implementation is owner-managed and needs its own verified rendering workflow.
  • Content gated behind a click/tab, a JavaScript-only redirect, or hash-only navigation added by a theme script or app embed is a separate defect from template output — apply the generic-http-html guidance above at the script that owns that behavior.
 
Official sources
 
 
Platform-managed / ask the vendor
 
Status: platform-managed · Location: Vendor-owned renderer, page builder, or hosted storefront
 
Implementation is controlled by the platform or vendor.
  
Verify on this platform
 
  • Ask the vendor to demonstrate the uncached initial HTML returned to crawlers and users.
  
Caveats
  • Escalate when the platform cannot expose or configure its rendering mode.
  • Require one production-URL response comparison rather than accepting a claim that the browser eventually renders the content.
  • Ask the vendor to confirm content is not gated behind interaction, redirects are not JavaScript-only, and routes are not hash-only.
 
Official sources
 
 
 
 
 How to verify 
 
  1. Fetch the public URL without JavaScript.
  2. Compare initial HTML and rendered DOM for the same title, H1, primary links, and content.
  3. Confirm important content and links are reachable without simulating a click, tab switch, or scroll, any redirect resolves at the HTTP or meta-refresh layer rather than only via JavaScript, and routes are individually fetchable rather than hash-only.
  4. Rerun Render Gap after deployment.
 
Escalate when
 
Escalate when the rendering layer is vendor-controlled, server rendering changes routing or authentication, or the raw and rendered views cannot be reproduced consistently.
 
 
 
 
 
 
 
Raw vs. Rendered HTML Checker · one finding
 
JavaScript redirects the page
 
Recommended action: Replace the JavaScript redirect with an appropriate server-side 3xx response to the final URL.
 
Fix principle: Make critical content available in build-time or request-time server output; diagnose browser-only data paths rather than treating framework client-component syntax as proof that initial HTML is missing.
 
 
 
 Implementation for your setup 
 
Confirm first: View source lacks critical content that appears after rendering. A non-rendering fetch receives a shell or materially incomplete page. Critical content, a real navigable link, or the page's true destination or route only exists after a script runs — including content gated behind a click or scroll interaction, a client-side redirect, hash-only routing, or a connection type (such as WebSocket) Googlebot does not support.
 
Do not apply when: Critical content is already present in the initial HTML and only presentation is hydrated. The observed difference comes from personalization that is intentionally unavailable to crawlers. The content, link, or route is reachable without any click, scroll, or persistent client-side connection, and any redirect to it is a real HTTP or meta-refresh redirect rather than a JavaScript-only one.
 
Likely control points: cms-app · server · edge-cdn
 
   
Choose the layer that owns the final response.
 
 
 
Generic HTTP / HTML
 
Status: supported · Location: Build pipeline, application server, or origin templates
 
Steps
  1. Choose build-time prerendering for content known at release time or request-time server rendering for content needed per request.
  2. Render the critical title, heading, links, and main content into the response, then hydrate only the interactions that need a browser.
  3. Reveal important content in the DOM without requiring a click, tab switch, or scroll to trigger it — Google Search does not interact with the page, so use CSS or an interaction-independent method (for example IntersectionObserver-based lazy loading) instead of loading content only on user action.
  4. Replace a client-side-only redirect with a real server-side HTTP redirect (or, when that is not feasible, a meta refresh); use a JavaScript redirect only as a last resort, since a rendering failure can mean Google never observes it.
  5. Replace hash-only routes (for example /#/products) with real, individually navigable URLs served through the History API or server-side routing, so each state has its own crawlable address.
  6. If content depends on a WebSocket or WebRTC connection established client-side, provide an HTTP-reachable equivalent or fallback for that same critical content, since Googlebot only retrieves content over HTTP.
  
Verify on this platform
 
  • Fetch the final public response without executing JavaScript and compare its critical content with the rendered page and Search Console live test.
  • Confirm important content and primary navigation links are present in the rendered DOM without simulating a click, tab switch, or scroll, and that the page's real destination and individual routes resolve to distinct HTTP-fetchable URLs rather than only a hash fragment or a WebSocket-delivered update.
 
Rollback
  1. Restore the prior renderer, redirect method, or routing approach while retaining the confirmed working response path if the change breaks user functionality.
 
Caveats
  • Do not default to user-agent-based dynamic rendering; Google describes it as a workaround rather than a recommended long-term solution.
  • Trace data loaded only in effects, browser-only APIs, disabled SSR, or an app shell before changing the rendering architecture.
  • A rendered page that looks like a soft 404 is usually the same underlying defect at its most severe: confirm whether content is simply late, hidden behind interaction, or genuinely absent, and apply the matching step above rather than treating it as a distinct problem.
 
Official sources
 
 
Next.js / Vercel
 
Status: supported · Location: App Router Server/Client Component boundaries or Pages Router rendering method
 
Steps
  1. In the App Router, keep critical fetching and document content in server-rendered output; isolate only interactive code behind Client Component boundaries.
  2. In the Pages Router, use static generation or request-time server rendering for critical content instead of loading it only after mount.
  3. Remove an unintended dynamic import with ssr: false, useEffect-only fetch, browser-only guard, or app-shell dependency from the critical path.
  
Verify on this platform
 
  • Inspect the deployed response without executing JavaScript, then rerun Render Gap and the Search Console live test on the same production URL.
 
Rollback
  1. Revert the affected route or component boundary if the deployment causes a functional regression.
 
Caveats
  • A Next.js "use client" directive does not by itself mean missing initial HTML: Client Components are prerendered on the first load.
  • Skipping SSR with ssr: false is supported only for Client Components and can intentionally remove their server-rendered output.
  • A client-side router.push() redirect, hash-only route, or client-established WebSocket is a code-level defect independent of the App/Pages Router choice — apply the generic-http-html guidance above (server-side redirect, History-API routing, HTTP fallback) at the component that owns that behavior.
 
Official sources
 
 
Vue / Nuxt
 
Status: supported · Location: Nuxt route rendering and deployment preset
 
Steps
  1. For Nuxt 4, keep universal rendering enabled for the route or prerender the route when its content is known at build time.
  2. Deploy with the Nuxt preset that matches the real host and verify the server or static output is being served.
  3. For plain Vue, select and verify the actual SSR architecture and host before applying implementation steps.
  
Verify on this platform
 
  • Fetch the deployed route without browser execution and confirm the critical content exists in the response; then rerun Render Gap.
 
Rollback
  1. Restore the prior Nuxt route rule, prerender list, or deployment preset if the route regresses.
 
Caveats
  • Plain Vue implementation is not verified by this recipe unless the site’s real SSR setup and deployment host are identified.
  • Client-only data fetching can still create a gap even when the application uses an SSR-capable framework.
  • A router-only (hash mode) route, a client-side redirect, or a client-established WebSocket is a Vue Router or application-code defect independent of Nuxt's rendering mode — apply the generic-http-html guidance above at the component or router configuration that owns it.
 
Official sources
 
 
WordPress
 
Status: supported · Location: Native classic/block theme template and post-content output
 
Steps
  1. For a classic theme, render the intended entry content through the selected template and the_content().
  2. For a block theme, keep the Post Content block in the applicable template and verify the template hierarchy selects it.
  
Verify on this platform
 
  • View the logged-out public response and confirm the native template emits the critical content before browser scripts run.
 
Rollback
  1. Restore the prior native template or template part if the published layout or content regresses.
 
Caveats
  • These steps cover native classic and block themes only.
  • A page builder or headless WordPress frontend is owner-managed; use that rendering system’s verified workflow instead of assuming core theme controls own the output.
  • Content gated behind a click/tab/accordion, a JavaScript-only redirect, or hash-only navigation added by a theme or plugin script is a separate defect from template output — apply the generic-http-html guidance above at the script that owns that behavior.
 
Official sources
 
 
Shopify
 
Status: supported · Location: Online Store Liquid or JSON theme templates
 
Steps
  1. Duplicate the active theme and make the rendering correction in the duplicate Liquid or JSON template.
  2. Preview representative product, collection, and content routes before publishing the corrected theme.
  
Verify on this platform
 
  • Inspect the preview and then published storefront response without browser execution and confirm the critical content is present.
 
Rollback
  1. Republish the previous theme if the new theme regresses storefront content or functionality.
 
Caveats
  • These steps apply only to Shopify Online Store Liquid/JSON themes.
  • An app-owned storefront or Hydrogen implementation is owner-managed and needs its own verified rendering workflow.
  • Content gated behind a click/tab, a JavaScript-only redirect, or hash-only navigation added by a theme script or app embed is a separate defect from template output — apply the generic-http-html guidance above at the script that owns that behavior.
 
Official sources
 
 
Platform-managed / ask the vendor
 
Status: platform-managed · Location: Vendor-owned renderer, page builder, or hosted storefront
 
Implementation is controlled by the platform or vendor.
  
Verify on this platform
 
  • Ask the vendor to demonstrate the uncached initial HTML returned to crawlers and users.
  
Caveats
  • Escalate when the platform cannot expose or configure its rendering mode.
  • Require one production-URL response comparison rather than accepting a claim that the browser eventually renders the content.
  • Ask the vendor to confirm content is not gated behind interaction, redirects are not JavaScript-only, and routes are not hash-only.
 
Official sources
 
 
 
 
 How to verify 
 
  1. Fetch the public URL without JavaScript.
  2. Compare initial HTML and rendered DOM for the same title, H1, primary links, and content.
  3. Confirm important content and links are reachable without simulating a click, tab switch, or scroll, any redirect resolves at the HTTP or meta-refresh layer rather than only via JavaScript, and routes are individually fetchable rather than hash-only.
  4. Rerun Render Gap after deployment.
 
Escalate when
 
Escalate when the rendering layer is vendor-controlled, server rendering changes routing or authentication, or the raw and rendered views cannot be reproduced consistently.
 
 
 
 
 
 
 
Raw vs. Rendered HTML Checker · one finding
 
Structured data appears only after rendering
 
Recommended action: Emit the validated JSON-LD in initial HTML instead of inserting it only after JavaScript runs.
 
Fix principle: Make critical content available in build-time or request-time server output; diagnose browser-only data paths rather than treating framework client-component syntax as proof that initial HTML is missing.
 
 
 
 Implementation for your setup 
 
Confirm first: View source lacks critical content that appears after rendering. A non-rendering fetch receives a shell or materially incomplete page. Critical content, a real navigable link, or the page's true destination or route only exists after a script runs — including content gated behind a click or scroll interaction, a client-side redirect, hash-only routing, or a connection type (such as WebSocket) Googlebot does not support.
 
Do not apply when: Critical content is already present in the initial HTML and only presentation is hydrated. The observed difference comes from personalization that is intentionally unavailable to crawlers. The content, link, or route is reachable without any click, scroll, or persistent client-side connection, and any redirect to it is a real HTTP or meta-refresh redirect rather than a JavaScript-only one.
 
Likely control points: cms-app · server · edge-cdn
 
   
Choose the layer that owns the final response.
 
 
 
Generic HTTP / HTML
 
Status: supported · Location: Build pipeline, application server, or origin templates
 
Steps
  1. Choose build-time prerendering for content known at release time or request-time server rendering for content needed per request.
  2. Render the critical title, heading, links, and main content into the response, then hydrate only the interactions that need a browser.
  3. Reveal important content in the DOM without requiring a click, tab switch, or scroll to trigger it — Google Search does not interact with the page, so use CSS or an interaction-independent method (for example IntersectionObserver-based lazy loading) instead of loading content only on user action.
  4. Replace a client-side-only redirect with a real server-side HTTP redirect (or, when that is not feasible, a meta refresh); use a JavaScript redirect only as a last resort, since a rendering failure can mean Google never observes it.
  5. Replace hash-only routes (for example /#/products) with real, individually navigable URLs served through the History API or server-side routing, so each state has its own crawlable address.
  6. If content depends on a WebSocket or WebRTC connection established client-side, provide an HTTP-reachable equivalent or fallback for that same critical content, since Googlebot only retrieves content over HTTP.
  
Verify on this platform
 
  • Fetch the final public response without executing JavaScript and compare its critical content with the rendered page and Search Console live test.
  • Confirm important content and primary navigation links are present in the rendered DOM without simulating a click, tab switch, or scroll, and that the page's real destination and individual routes resolve to distinct HTTP-fetchable URLs rather than only a hash fragment or a WebSocket-delivered update.
 
Rollback
  1. Restore the prior renderer, redirect method, or routing approach while retaining the confirmed working response path if the change breaks user functionality.
 
Caveats
  • Do not default to user-agent-based dynamic rendering; Google describes it as a workaround rather than a recommended long-term solution.
  • Trace data loaded only in effects, browser-only APIs, disabled SSR, or an app shell before changing the rendering architecture.
  • A rendered page that looks like a soft 404 is usually the same underlying defect at its most severe: confirm whether content is simply late, hidden behind interaction, or genuinely absent, and apply the matching step above rather than treating it as a distinct problem.
 
Official sources
 
 
Next.js / Vercel
 
Status: supported · Location: App Router Server/Client Component boundaries or Pages Router rendering method
 
Steps
  1. In the App Router, keep critical fetching and document content in server-rendered output; isolate only interactive code behind Client Component boundaries.
  2. In the Pages Router, use static generation or request-time server rendering for critical content instead of loading it only after mount.
  3. Remove an unintended dynamic import with ssr: false, useEffect-only fetch, browser-only guard, or app-shell dependency from the critical path.
  
Verify on this platform
 
  • Inspect the deployed response without executing JavaScript, then rerun Render Gap and the Search Console live test on the same production URL.
 
Rollback
  1. Revert the affected route or component boundary if the deployment causes a functional regression.
 
Caveats
  • A Next.js "use client" directive does not by itself mean missing initial HTML: Client Components are prerendered on the first load.
  • Skipping SSR with ssr: false is supported only for Client Components and can intentionally remove their server-rendered output.
  • A client-side router.push() redirect, hash-only route, or client-established WebSocket is a code-level defect independent of the App/Pages Router choice — apply the generic-http-html guidance above (server-side redirect, History-API routing, HTTP fallback) at the component that owns that behavior.
 
Official sources
 
 
Vue / Nuxt
 
Status: supported · Location: Nuxt route rendering and deployment preset
 
Steps
  1. For Nuxt 4, keep universal rendering enabled for the route or prerender the route when its content is known at build time.
  2. Deploy with the Nuxt preset that matches the real host and verify the server or static output is being served.
  3. For plain Vue, select and verify the actual SSR architecture and host before applying implementation steps.
  
Verify on this platform
 
  • Fetch the deployed route without browser execution and confirm the critical content exists in the response; then rerun Render Gap.
 
Rollback
  1. Restore the prior Nuxt route rule, prerender list, or deployment preset if the route regresses.
 
Caveats
  • Plain Vue implementation is not verified by this recipe unless the site’s real SSR setup and deployment host are identified.
  • Client-only data fetching can still create a gap even when the application uses an SSR-capable framework.
  • A router-only (hash mode) route, a client-side redirect, or a client-established WebSocket is a Vue Router or application-code defect independent of Nuxt's rendering mode — apply the generic-http-html guidance above at the component or router configuration that owns it.
 
Official sources
 
 
WordPress
 
Status: supported · Location: Native classic/block theme template and post-content output
 
Steps
  1. For a classic theme, render the intended entry content through the selected template and the_content().
  2. For a block theme, keep the Post Content block in the applicable template and verify the template hierarchy selects it.
  
Verify on this platform
 
  • View the logged-out public response and confirm the native template emits the critical content before browser scripts run.
 
Rollback
  1. Restore the prior native template or template part if the published layout or content regresses.
 
Caveats
  • These steps cover native classic and block themes only.
  • A page builder or headless WordPress frontend is owner-managed; use that rendering system’s verified workflow instead of assuming core theme controls own the output.
  • Content gated behind a click/tab/accordion, a JavaScript-only redirect, or hash-only navigation added by a theme or plugin script is a separate defect from template output — apply the generic-http-html guidance above at the script that owns that behavior.
 
Official sources
 
 
Shopify
 
Status: supported · Location: Online Store Liquid or JSON theme templates
 
Steps
  1. Duplicate the active theme and make the rendering correction in the duplicate Liquid or JSON template.
  2. Preview representative product, collection, and content routes before publishing the corrected theme.
  
Verify on this platform
 
  • Inspect the preview and then published storefront response without browser execution and confirm the critical content is present.
 
Rollback
  1. Republish the previous theme if the new theme regresses storefront content or functionality.
 
Caveats
  • These steps apply only to Shopify Online Store Liquid/JSON themes.
  • An app-owned storefront or Hydrogen implementation is owner-managed and needs its own verified rendering workflow.
  • Content gated behind a click/tab, a JavaScript-only redirect, or hash-only navigation added by a theme script or app embed is a separate defect from template output — apply the generic-http-html guidance above at the script that owns that behavior.
 
Official sources
 
 
Platform-managed / ask the vendor
 
Status: platform-managed · Location: Vendor-owned renderer, page builder, or hosted storefront
 
Implementation is controlled by the platform or vendor.
  
Verify on this platform
 
  • Ask the vendor to demonstrate the uncached initial HTML returned to crawlers and users.
  
Caveats
  • Escalate when the platform cannot expose or configure its rendering mode.
  • Require one production-URL response comparison rather than accepting a claim that the browser eventually renders the content.
  • Ask the vendor to confirm content is not gated behind interaction, redirects are not JavaScript-only, and routes are not hash-only.
 
Official sources
 
 
 
 
 How to verify 
 
  1. Fetch the public URL without JavaScript.
  2. Compare initial HTML and rendered DOM for the same title, H1, primary links, and content.
  3. Confirm important content and links are reachable without simulating a click, tab switch, or scroll, any redirect resolves at the HTTP or meta-refresh layer rather than only via JavaScript, and routes are individually fetchable rather than hash-only.
  4. Rerun Render Gap after deployment.
 
Escalate when
 
Escalate when the rendering layer is vendor-controlled, server rendering changes routing or authentication, or the raw and rendered views cannot be reproduced consistently.
 
 
 
 
 
 
 
Raw vs. Rendered HTML Checker · one finding
 
Page depends on a WebSocket during render
 
Recommended action: Render essential content without requiring an open WebSocket, and provide a resilient HTTP or server-rendered fallback.
 
Fix principle: Make critical content available in build-time or request-time server output; diagnose browser-only data paths rather than treating framework client-component syntax as proof that initial HTML is missing.
 
 
 
 Implementation for your setup 
 
Confirm first: View source lacks critical content that appears after rendering. A non-rendering fetch receives a shell or materially incomplete page. Critical content, a real navigable link, or the page's true destination or route only exists after a script runs — including content gated behind a click or scroll interaction, a client-side redirect, hash-only routing, or a connection type (such as WebSocket) Googlebot does not support.
 
Do not apply when: Critical content is already present in the initial HTML and only presentation is hydrated. The observed difference comes from personalization that is intentionally unavailable to crawlers. The content, link, or route is reachable without any click, scroll, or persistent client-side connection, and any redirect to it is a real HTTP or meta-refresh redirect rather than a JavaScript-only one.
 
Likely control points: cms-app · server · edge-cdn
 
   
Choose the layer that owns the final response.
 
 
 
Generic HTTP / HTML
 
Status: supported · Location: Build pipeline, application server, or origin templates
 
Steps
  1. Choose build-time prerendering for content known at release time or request-time server rendering for content needed per request.
  2. Render the critical title, heading, links, and main content into the response, then hydrate only the interactions that need a browser.
  3. Reveal important content in the DOM without requiring a click, tab switch, or scroll to trigger it — Google Search does not interact with the page, so use CSS or an interaction-independent method (for example IntersectionObserver-based lazy loading) instead of loading content only on user action.
  4. Replace a client-side-only redirect with a real server-side HTTP redirect (or, when that is not feasible, a meta refresh); use a JavaScript redirect only as a last resort, since a rendering failure can mean Google never observes it.
  5. Replace hash-only routes (for example /#/products) with real, individually navigable URLs served through the History API or server-side routing, so each state has its own crawlable address.
  6. If content depends on a WebSocket or WebRTC connection established client-side, provide an HTTP-reachable equivalent or fallback for that same critical content, since Googlebot only retrieves content over HTTP.
  
Verify on this platform
 
  • Fetch the final public response without executing JavaScript and compare its critical content with the rendered page and Search Console live test.
  • Confirm important content and primary navigation links are present in the rendered DOM without simulating a click, tab switch, or scroll, and that the page's real destination and individual routes resolve to distinct HTTP-fetchable URLs rather than only a hash fragment or a WebSocket-delivered update.
 
Rollback
  1. Restore the prior renderer, redirect method, or routing approach while retaining the confirmed working response path if the change breaks user functionality.
 
Caveats
  • Do not default to user-agent-based dynamic rendering; Google describes it as a workaround rather than a recommended long-term solution.
  • Trace data loaded only in effects, browser-only APIs, disabled SSR, or an app shell before changing the rendering architecture.
  • A rendered page that looks like a soft 404 is usually the same underlying defect at its most severe: confirm whether content is simply late, hidden behind interaction, or genuinely absent, and apply the matching step above rather than treating it as a distinct problem.
 
Official sources
 
 
Next.js / Vercel
 
Status: supported · Location: App Router Server/Client Component boundaries or Pages Router rendering method
 
Steps
  1. In the App Router, keep critical fetching and document content in server-rendered output; isolate only interactive code behind Client Component boundaries.
  2. In the Pages Router, use static generation or request-time server rendering for critical content instead of loading it only after mount.
  3. Remove an unintended dynamic import with ssr: false, useEffect-only fetch, browser-only guard, or app-shell dependency from the critical path.
  
Verify on this platform
 
  • Inspect the deployed response without executing JavaScript, then rerun Render Gap and the Search Console live test on the same production URL.
 
Rollback
  1. Revert the affected route or component boundary if the deployment causes a functional regression.
 
Caveats
  • A Next.js "use client" directive does not by itself mean missing initial HTML: Client Components are prerendered on the first load.
  • Skipping SSR with ssr: false is supported only for Client Components and can intentionally remove their server-rendered output.
  • A client-side router.push() redirect, hash-only route, or client-established WebSocket is a code-level defect independent of the App/Pages Router choice — apply the generic-http-html guidance above (server-side redirect, History-API routing, HTTP fallback) at the component that owns that behavior.
 
Official sources
 
 
Vue / Nuxt
 
Status: supported · Location: Nuxt route rendering and deployment preset
 
Steps
  1. For Nuxt 4, keep universal rendering enabled for the route or prerender the route when its content is known at build time.
  2. Deploy with the Nuxt preset that matches the real host and verify the server or static output is being served.
  3. For plain Vue, select and verify the actual SSR architecture and host before applying implementation steps.
  
Verify on this platform
 
  • Fetch the deployed route without browser execution and confirm the critical content exists in the response; then rerun Render Gap.
 
Rollback
  1. Restore the prior Nuxt route rule, prerender list, or deployment preset if the route regresses.
 
Caveats
  • Plain Vue implementation is not verified by this recipe unless the site’s real SSR setup and deployment host are identified.
  • Client-only data fetching can still create a gap even when the application uses an SSR-capable framework.
  • A router-only (hash mode) route, a client-side redirect, or a client-established WebSocket is a Vue Router or application-code defect independent of Nuxt's rendering mode — apply the generic-http-html guidance above at the component or router configuration that owns it.
 
Official sources
 
 
WordPress
 
Status: supported · Location: Native classic/block theme template and post-content output
 
Steps
  1. For a classic theme, render the intended entry content through the selected template and the_content().
  2. For a block theme, keep the Post Content block in the applicable template and verify the template hierarchy selects it.
  
Verify on this platform
 
  • View the logged-out public response and confirm the native template emits the critical content before browser scripts run.
 
Rollback
  1. Restore the prior native template or template part if the published layout or content regresses.
 
Caveats
  • These steps cover native classic and block themes only.
  • A page builder or headless WordPress frontend is owner-managed; use that rendering system’s verified workflow instead of assuming core theme controls own the output.
  • Content gated behind a click/tab/accordion, a JavaScript-only redirect, or hash-only navigation added by a theme or plugin script is a separate defect from template output — apply the generic-http-html guidance above at the script that owns that behavior.
 
Official sources
 
 
Shopify
 
Status: supported · Location: Online Store Liquid or JSON theme templates
 
Steps
  1. Duplicate the active theme and make the rendering correction in the duplicate Liquid or JSON template.
  2. Preview representative product, collection, and content routes before publishing the corrected theme.
  
Verify on this platform
 
  • Inspect the preview and then published storefront response without browser execution and confirm the critical content is present.
 
Rollback
  1. Republish the previous theme if the new theme regresses storefront content or functionality.
 
Caveats
  • These steps apply only to Shopify Online Store Liquid/JSON themes.
  • An app-owned storefront or Hydrogen implementation is owner-managed and needs its own verified rendering workflow.
  • Content gated behind a click/tab, a JavaScript-only redirect, or hash-only navigation added by a theme script or app embed is a separate defect from template output — apply the generic-http-html guidance above at the script that owns that behavior.
 
Official sources
 
 
Platform-managed / ask the vendor
 
Status: platform-managed · Location: Vendor-owned renderer, page builder, or hosted storefront
 
Implementation is controlled by the platform or vendor.
  
Verify on this platform
 
  • Ask the vendor to demonstrate the uncached initial HTML returned to crawlers and users.
  
Caveats
  • Escalate when the platform cannot expose or configure its rendering mode.
  • Require one production-URL response comparison rather than accepting a claim that the browser eventually renders the content.
  • Ask the vendor to confirm content is not gated behind interaction, redirects are not JavaScript-only, and routes are not hash-only.
 
Official sources
 
 
 
 
 How to verify 
 
  1. Fetch the public URL without JavaScript.
  2. Compare initial HTML and rendered DOM for the same title, H1, primary links, and content.
  3. Confirm important content and links are reachable without simulating a click, tab switch, or scroll, any redirect resolves at the HTTP or meta-refresh layer rather than only via JavaScript, and routes are individually fetchable rather than hash-only.
  4. Rerun Render Gap after deployment.
 
Escalate when
 
Escalate when the rendering layer is vendor-controlled, server rendering changes routing or authentication, or the raw and rendered views cannot be reproduced consistently.
 
 
 
 
 
 
 
Raw vs. Rendered HTML Checker · one finding
 
Page relies on hash routing
 
Recommended action: Switch the router to history-mode paths that the server can resolve without a URL fragment.
 
Fix principle: Make critical content available in build-time or request-time server output; diagnose browser-only data paths rather than treating framework client-component syntax as proof that initial HTML is missing.
 
 
 
 Implementation for your setup 
 
Confirm first: View source lacks critical content that appears after rendering. A non-rendering fetch receives a shell or materially incomplete page. Critical content, a real navigable link, or the page's true destination or route only exists after a script runs — including content gated behind a click or scroll interaction, a client-side redirect, hash-only routing, or a connection type (such as WebSocket) Googlebot does not support.
 
Do not apply when: Critical content is already present in the initial HTML and only presentation is hydrated. The observed difference comes from personalization that is intentionally unavailable to crawlers. The content, link, or route is reachable without any click, scroll, or persistent client-side connection, and any redirect to it is a real HTTP or meta-refresh redirect rather than a JavaScript-only one.
 
Likely control points: cms-app · server · edge-cdn
 
   
Choose the layer that owns the final response.
 
 
 
Generic HTTP / HTML
 
Status: supported · Location: Build pipeline, application server, or origin templates
 
Steps
  1. Choose build-time prerendering for content known at release time or request-time server rendering for content needed per request.
  2. Render the critical title, heading, links, and main content into the response, then hydrate only the interactions that need a browser.
  3. Reveal important content in the DOM without requiring a click, tab switch, or scroll to trigger it — Google Search does not interact with the page, so use CSS or an interaction-independent method (for example IntersectionObserver-based lazy loading) instead of loading content only on user action.
  4. Replace a client-side-only redirect with a real server-side HTTP redirect (or, when that is not feasible, a meta refresh); use a JavaScript redirect only as a last resort, since a rendering failure can mean Google never observes it.
  5. Replace hash-only routes (for example /#/products) with real, individually navigable URLs served through the History API or server-side routing, so each state has its own crawlable address.
  6. If content depends on a WebSocket or WebRTC connection established client-side, provide an HTTP-reachable equivalent or fallback for that same critical content, since Googlebot only retrieves content over HTTP.
  
Verify on this platform
 
  • Fetch the final public response without executing JavaScript and compare its critical content with the rendered page and Search Console live test.
  • Confirm important content and primary navigation links are present in the rendered DOM without simulating a click, tab switch, or scroll, and that the page's real destination and individual routes resolve to distinct HTTP-fetchable URLs rather than only a hash fragment or a WebSocket-delivered update.
 
Rollback
  1. Restore the prior renderer, redirect method, or routing approach while retaining the confirmed working response path if the change breaks user functionality.
 
Caveats
  • Do not default to user-agent-based dynamic rendering; Google describes it as a workaround rather than a recommended long-term solution.
  • Trace data loaded only in effects, browser-only APIs, disabled SSR, or an app shell before changing the rendering architecture.
  • A rendered page that looks like a soft 404 is usually the same underlying defect at its most severe: confirm whether content is simply late, hidden behind interaction, or genuinely absent, and apply the matching step above rather than treating it as a distinct problem.
 
Official sources
 
 
Next.js / Vercel
 
Status: supported · Location: App Router Server/Client Component boundaries or Pages Router rendering method
 
Steps
  1. In the App Router, keep critical fetching and document content in server-rendered output; isolate only interactive code behind Client Component boundaries.
  2. In the Pages Router, use static generation or request-time server rendering for critical content instead of loading it only after mount.
  3. Remove an unintended dynamic import with ssr: false, useEffect-only fetch, browser-only guard, or app-shell dependency from the critical path.
  
Verify on this platform
 
  • Inspect the deployed response without executing JavaScript, then rerun Render Gap and the Search Console live test on the same production URL.
 
Rollback
  1. Revert the affected route or component boundary if the deployment causes a functional regression.
 
Caveats
  • A Next.js "use client" directive does not by itself mean missing initial HTML: Client Components are prerendered on the first load.
  • Skipping SSR with ssr: false is supported only for Client Components and can intentionally remove their server-rendered output.
  • A client-side router.push() redirect, hash-only route, or client-established WebSocket is a code-level defect independent of the App/Pages Router choice — apply the generic-http-html guidance above (server-side redirect, History-API routing, HTTP fallback) at the component that owns that behavior.
 
Official sources
 
 
Vue / Nuxt
 
Status: supported · Location: Nuxt route rendering and deployment preset
 
Steps
  1. For Nuxt 4, keep universal rendering enabled for the route or prerender the route when its content is known at build time.
  2. Deploy with the Nuxt preset that matches the real host and verify the server or static output is being served.
  3. For plain Vue, select and verify the actual SSR architecture and host before applying implementation steps.
  
Verify on this platform
 
  • Fetch the deployed route without browser execution and confirm the critical content exists in the response; then rerun Render Gap.
 
Rollback
  1. Restore the prior Nuxt route rule, prerender list, or deployment preset if the route regresses.
 
Caveats
  • Plain Vue implementation is not verified by this recipe unless the site’s real SSR setup and deployment host are identified.
  • Client-only data fetching can still create a gap even when the application uses an SSR-capable framework.
  • A router-only (hash mode) route, a client-side redirect, or a client-established WebSocket is a Vue Router or application-code defect independent of Nuxt's rendering mode — apply the generic-http-html guidance above at the component or router configuration that owns it.
 
Official sources
 
 
WordPress
 
Status: supported · Location: Native classic/block theme template and post-content output
 
Steps
  1. For a classic theme, render the intended entry content through the selected template and the_content().
  2. For a block theme, keep the Post Content block in the applicable template and verify the template hierarchy selects it.
  
Verify on this platform
 
  • View the logged-out public response and confirm the native template emits the critical content before browser scripts run.
 
Rollback
  1. Restore the prior native template or template part if the published layout or content regresses.
 
Caveats
  • These steps cover native classic and block themes only.
  • A page builder or headless WordPress frontend is owner-managed; use that rendering system’s verified workflow instead of assuming core theme controls own the output.
  • Content gated behind a click/tab/accordion, a JavaScript-only redirect, or hash-only navigation added by a theme or plugin script is a separate defect from template output — apply the generic-http-html guidance above at the script that owns that behavior.
 
Official sources
 
 
Shopify
 
Status: supported · Location: Online Store Liquid or JSON theme templates
 
Steps
  1. Duplicate the active theme and make the rendering correction in the duplicate Liquid or JSON template.
  2. Preview representative product, collection, and content routes before publishing the corrected theme.
  
Verify on this platform
 
  • Inspect the preview and then published storefront response without browser execution and confirm the critical content is present.
 
Rollback
  1. Republish the previous theme if the new theme regresses storefront content or functionality.
 
Caveats
  • These steps apply only to Shopify Online Store Liquid/JSON themes.
  • An app-owned storefront or Hydrogen implementation is owner-managed and needs its own verified rendering workflow.
  • Content gated behind a click/tab, a JavaScript-only redirect, or hash-only navigation added by a theme script or app embed is a separate defect from template output — apply the generic-http-html guidance above at the script that owns that behavior.
 
Official sources
 
 
Platform-managed / ask the vendor
 
Status: platform-managed · Location: Vendor-owned renderer, page builder, or hosted storefront
 
Implementation is controlled by the platform or vendor.
  
Verify on this platform
 
  • Ask the vendor to demonstrate the uncached initial HTML returned to crawlers and users.
  
Caveats
  • Escalate when the platform cannot expose or configure its rendering mode.
  • Require one production-URL response comparison rather than accepting a claim that the browser eventually renders the content.
  • Ask the vendor to confirm content is not gated behind interaction, redirects are not JavaScript-only, and routes are not hash-only.
 
Official sources
 
 
 
 
 How to verify 
 
  1. Fetch the public URL without JavaScript.
  2. Compare initial HTML and rendered DOM for the same title, H1, primary links, and content.
  3. Confirm important content and links are reachable without simulating a click, tab switch, or scroll, any redirect resolves at the HTTP or meta-refresh layer rather than only via JavaScript, and routes are individually fetchable rather than hash-only.
  4. Rerun Render Gap after deployment.
 
Escalate when
 
Escalate when the rendering layer is vendor-controlled, server rendering changes routing or authentication, or the raw and rendered views cannot be reproduced consistently.
 
 
 
 
  
 
 
     
  •  Warnings Initial document head closes unexpectedly early Fix: Fix the malformed head markup so metadata stays inside one valid <head> element in the initial HTML. 
  •  Errors Title is missing Fix: Add one concise, unique <title> to the initial HTML that names the page’s primary topic. 
  •  Warnings Title changes after rendering Fix: Make the server and rendered <title> values identical unless the client-side change is deliberately required. 
  •  Errors Title appears only after JavaScript Fix: Emit the final <title> in the initial HTML instead of relying on JavaScript to insert it. 
  •  Warnings Meta description is missing Fix: Add a page-specific meta description to the initial HTML that accurately summarizes the content. 
  •  Warnings Meta description changes after rendering Fix: Align the initial and rendered meta descriptions so crawlers receive one consistent summary. 
  •  Warnings Rendered images lack alt attributes Fix: Add concise alt text to meaningful rendered images and empty alt attributes to decorative ones. 
  •  Warnings Rendering produces console errors Fix: Fix the named client-side exception and confirm essential content still renders on a cold load. 
  •  Warnings Rendering has failed resource requests Fix: Restore, correctly route, or remove each failed resource request required by the rendered output. 
  •  Information Structured data is absent Fix: Add accurate JSON-LD for the page’s primary supported entity when structured data is appropriate. 
  •  Warnings Viewport meta tag is missing Fix: Add <meta name="viewport" content="width=device-width, initial-scale=1"> to the initial head. 
  •  Warnings Title element is outside the HTML head Fix: Move the title into the document head and keep exactly one non-empty title value there. 
  •  Warnings Canonical element is outside the HTML head Fix: Move the intended canonical link into the document head and remove body-level canonical declarations. 
    •