Fastest fix: open one failing URL in the Rich Results Test, read the error string verbatim, then view-source the page and look at the <script type="application/ld+json"> block. The breakage is almost always one of four things — a renamed frontmatter field the JSON-LD still references by its old name, a framework serializer that changed a date or array format, a new layout wrapper that dropped the script before it reached <head>, or a conditional render path that now excludes a batch of pages. You do not need to rewrite the schema. Find the one field that regressed and patch it.
This usually surfaces a week after you refactored your article layout, upgraded Astro / Next.js / Hugo, or renamed a content-collection field, when Search Console emails you “Structured data issues detected” and the Enhancements report (Search Console → left nav → Enhancements, listed per type: Articles, Breadcrumbs, Merchant listings, and so on) shows a spike of red.
Heads-up for June 2026: FAQ rich results are gone. Google stopped showing the FAQ rich result in Search on May 7, 2026, removed the FAQ report and FAQ support from the Rich Results Test in June 2026, and will drop FAQ data from the Search Console API in August 2026 (Google’s FAQ changelog). HowTo rich results were already removed on desktop back in September 2023. The
FAQPage/HowTomarkup is still valid Schema.org and is harmless to leave in place — it just no longer earns a SERP feature, so do not chase a “broken FAQPage” rich result that no longer exists.
Identify which case you are in (about 15 seconds)
Open the failing URL in the Rich Results Test and read the exact error message, not your interpretation of it. The error wording maps to a specific cause:
| Rich Results Test error | Most likely cause |
|---|---|
Missing field "datePublished" / "author" / "image" | Renamed frontmatter field; JSON-LD still references the old name and gets undefined |
Invalid object type for field "X" | Framework upgrade changed how a value serializes (Date → string, array → object) |
Parsing error: ... or “No items detected” / “No structured data detected” | The JSON-LD block is no longer in the rendered HTML — a wrapper, hydration, or conditional dropped it |
Either "image" or "thumbnailUrl" should be specified | Image helper now returns a relative URL or null |
BreadcrumbList: itemListElement must contain at least 2 items | Breadcrumb generator now returns 0 or 1 items for some routes |
Article: A value for the headline field is required | Title field renamed or now resolves to an empty string |
If you only see an error against FAQPage, ignore it: that type no longer produces a rich result and the Rich Results Test no longer reports on it as of June 2026.
Common causes, ranked by hit rate
1. Renamed a frontmatter field — JSON-LD still references the old name
You renamed pubDate to publishedAt in the content collection schema. The JSON-LD template still reads frontmatter.pubDate, which is now undefined. The output looks like:
{
"@context": "https://schema.org",
"@type": "Article",
"datePublished": null
}Google rejects null / missing required fields.
How to spot it: view-source the page, find the <script type="application/ld+json"> block, look for null, missing keys, or fields that should be populated but are empty strings.
Fix: grep the codebase for every field name your JSON-LD generator references and verify each one against the current frontmatter schema. A simple guard:
const datePublished = frontmatter.publishedAt ?? frontmatter.pubDate;
if (!datePublished) throw new Error(`Missing publishedAt for ${slug}`);Fail the build on missing required fields — quieter than catching it in Search Console two weeks later.
2. Framework upgrade changed serialization
A common gotcha after Astro / Next.js minor upgrades: Date objects used to serialize to ISO strings via JSON.stringify; now they serialize to {} or to a localized string. The same with arrays of objects being flattened.
How to spot it: diff view-source between the last working commit and current. Look for fields that used to be "2026-05-19T00:00:00.000Z" and are now "5/19/2026" or {}.
Fix: always coerce dates to ISO 8601 explicitly:
const datePublished = new Date(frontmatter.publishedAt).toISOString();And serialize arrays explicitly rather than relying on JSON.stringify defaults.
3. A new layout wrapper swallowed the JSON-LD block
You added a <MarketingShell> or <ArticleFrame> component around the article body. If that component renders its own <head> slot or strips children, your <script type="application/ld+json"> may no longer reach the document head.
How to spot it: Rich Results Test says “No structured data detected.” view-source the page: the JSON-LD <script> block is missing entirely. It was emitted in the template source but didn’t survive rendering.
Fix: in Astro, use <Fragment slot="head"> or render the script directly inside the layout’s <head>. In Next.js, use the <Head> component or App Router’s generateMetadata / Script with strategy="beforeInteractive". In Hugo, ensure your partial is included in head.html.
4. Conditional render path drops schema for a subset of pages
Your template has {frontmatter.draft ? null : <JsonLd />} or {frontmatter.type === 'guide' && <JsonLd />}. After a refactor, the condition now excludes more pages than intended — e.g., legacy articles where type is undefined.
How to spot it: Search Console Enhancements shows an exact count of “valid items” that dropped. Filter URLs and notice they all share a frontmatter trait (legacy date, missing field, specific category).
Fix: make the JSON-LD generator unconditional for the types Google still renders. Emit nothing only when a type is truly inapplicable to the page. For Article / BreadcrumbList / WebSite, always emit.
5. BreadcrumbList itemListElement count mismatch
After a route refactor, the breadcrumb generator returns 1 item for some routes (Home) or returns the same item twice (Home > Home > Article). Google requires at least 2 items and items must be unique positions.
{
"@context": "https://schema.org",
"@type": "BreadcrumbList",
"itemListElement": [
{ "@type": "ListItem", "position": 1, "name": "Home", "item": "https://yourdomain.com/" },
{ "@type": "ListItem", "position": 2, "name": "Troubleshooting", "item": "https://yourdomain.com/troubleshooting/" },
{ "@type": "ListItem", "position": 3, "name": "Article title" }
]
}Note: the last item must NOT have an item URL — it represents the current page.
A copy-ready Article + Breadcrumb template
{
"@context": "https://schema.org",
"@type": "Article",
"headline": "Article title under 110 characters",
"description": "One-sentence summary",
"image": "https://yourdomain.com/og/article.png",
"datePublished": "2026-05-19T00:00:00.000Z",
"dateModified": "2026-05-22T00:00:00.000Z",
"author": {
"@type": "Person",
"name": "Author Name",
"url": "https://yourdomain.com/about/"
},
"publisher": {
"@type": "Organization",
"name": "Site name",
"logo": {
"@type": "ImageObject",
"url": "https://yourdomain.com/logo.png"
}
},
"mainEntityOfPage": {
"@type": "WebPage",
"@id": "https://yourdomain.com/articles/article-slug/"
}
}Shortest fix path
In hit-rate order:
- Read the exact Rich Results Test error verbatim: it tells you the broken field
- View-source the page and inspect the JSON-LD block: find
null, missing key, or stale field name - Diff the template against the last working commit: most issues regress from one specific change
- Add a build-time JSON-LD validator that fails on missing required fields — prevents the next regression
- Re-request indexing in Search Console URL Inspection on a sample page; Enhancements report clears in 1-3 weeks
Prevention
- Validate raw JSON-LD syntax on every build with
schema-dtstype-checking (it makes a renamed or wrong-typed field a TypeScript error, not a runtime surprise). For ad-hoc syntax checks against the full Schema.org vocabulary, paste markup into the Schema Markup Validator — that is the generic syntax tool, while the Rich Results Test only covers types that still earn a Google rich result. - Never reference frontmatter fields directly in JSON-LD templates. Go through a typed helper that throws on missing required fields, so the build fails instead of Search Console catching it two weeks later.
- After any framework upgrade, run the Rich Results Test on one URL per content type before merging. Use Code Snippet mode for a not-yet-deployed branch, or URL mode against a preview deploy.
- Keep a “schema canary” route — a fixture page that emits every schema type you ship — and check it in CI so a layout change that drops the
<script>block fails fast. - Track the Enhancements report monthly. The count of valid items per type is your early-warning signal that a regression slipped past CI.
How to confirm it’s fixed
- Re-run the Rich Results Test on the same URL. It should now report the type as eligible with no errors. This is ground truth — it reflects Googlebot’s actual fetch and render.
view-sourcethe live page and confirm the<script type="application/ld+json">block is present, parses as JSON, and has the previously-missing field populated.- In Search Console, open URL Inspection on a sample page, click “Test live URL,” then “Request indexing.” The Enhancements count re-validates as Google re-crawls — expect 1-3 weeks for the red number to drop, but the live test confirms the fix immediately.
FAQ
Q: Will broken JSON-LD hurt my ranking? A: It hurts rich result eligibility, not the underlying ranking. Your blue-link result stays put; you just lose the eligible enhancement (breadcrumb trail, product price/rating, video thumbnail, and so on). For commerce, recipes, and events, the rich result loss is significant.
Q: My error is on FAQPage. Do I need to fix it?
A: No. As of June 2026 Google no longer renders FAQ rich results (the feature was removed May 7, 2026, and FAQ support was pulled from the Rich Results Test and the FAQ report in June 2026). The FAQPage markup is still valid Schema.org and is harmless to leave, but it earns no SERP feature, so do not spend time “fixing” it. Put your effort into Article, BreadcrumbList, and product/recipe/event types that still produce rich results.
Q: Should I remove the JSON-LD entirely if I cannot fix it quickly?
A: For a type that still earns a rich result, yes — shipping invalid schema for it is worse than shipping none, because Google logs the failures. Remove it, fix it offline, reinstate it. For already-deprecated types (FAQPage, HowTo) there is nothing to remove for SEO reasons; the markup is inert.
Q: Enhancements report still shows “Invalid” after I fixed it. How long until it clears? A: Search Console re-validates as Google re-crawls. Expect 1-3 weeks for the count to drop. Don’t wait on it — the Rich Results Test on a sample URL tells you immediately whether the fix worked.
Q: Rich Results Test says “Eligible” but Google does not show the rich result. A: Eligibility is necessary but not sufficient. Google also weighs content quality, freshness, and per-query intent, and may simply choose not to render the enhancement. Confirm the type is one Google still supports (check the structured data gallery) before assuming a bug.
Q: I have multiple JSON-LD blocks on one page. Is that OK?
A: Yes. One Article + one BreadcrumbList + one WebSite is standard, each in its own <script> tag. Just do not duplicate the same @type with conflicting values — Google may pick either one or ignore both.
Q: Which tool should I trust — Rich Results Test or the Schema Markup Validator? A: Both, for different jobs. The Rich Results Test answers “is this eligible for a Google rich result?” The Schema Markup Validator answers “is this structurally valid Schema.org?” across all 800+ types, including ones Google ignores. Use the validator to catch a syntax/typing bug, the Rich Results Test to confirm SERP eligibility.
Related articles
- Structured data rich results warning
- Breadcrumb JSON-LD mismatch
- FAQ schema invalid
- Article date JSON-LD mismatch
- Website JSON-LD inconsistency
Tags: #SEO #Troubleshooting #Debug #Structured data #JSON-LD