Home / Resources / Hydrogen issue library Each card starts with the symptom, names the fix direction, and points to a production note plus the checklist that should be used before the next release.
Issue category
SEO and crawlability Rendered content, canonical URLs, structured data, sitemap, and robots signals.
Product descriptions are missing from initial HTML Symptom
The PDP looks fine after JavaScript, but view source does not contain the product copy.
Fix
Move important product content into the route data and server-rendered response.
JSON-LD does not match visible product state Symptom
Structured data describes a different variant, price, availability, or canonical state.
Fix
Generate JSON-LD from the same selected product and variant state shown to shoppers.
Sitemap and robots were treated as deploy afterthoughts Symptom
Production crawl files do not match the storefront routes search engines should discover.
Fix
Own sitemap.xml, robots.txt, canonicals, and production route checks as launch QA.
Issue category
Performance and rendering SSR, loader data, caching, media, and browser-visible speed issues.
Primary homepage data loads after hydration Symptom
The homepage shell appears, then products arrive later through a client effect.
Fix
Move the common-path product data into the route loader and cache it deliberately.
Product content is visible only after client JavaScript Symptom
Important content fails the simple no-JavaScript or view-source check.
Fix
Treat product content as render-critical when it helps shoppers or crawlers.
Performance work starts without a checklist Symptom
The team tunes isolated components without naming API, media, third-party, and SSR boundaries.
Fix
Audit the page by request path, route data, cache behavior, image loading, and scripts.
Issue category
Cart, checkout, and pricing Cart state, checkout handoff, partner pricing, accounts, and analytics boundaries.
Checkout handoff risk is discovered too late Symptom
The storefront works until Shopify checkout, discounts, consent, or tracking need to agree.
Fix
Map cart state, checkout redirect, analytics, discount rules, and consent before launch.
Partner pricing leaks across the storefront Symptom
Eligibility, PDP display, cart math, and checkout discounts are handled by separate workarounds.
Fix
Draw one rule boundary for customer recognition and price application.
Apps assume a Liquid theme surface Symptom
A Shopify app works in theme context but has no clean custom storefront equivalent.
Fix
Classify each app as API-backed, script-only, checkout-only, replace, or remove.
Issue category
PDP and variant behavior Product page state, selected options, fallback variants, content, media, and availability.
Variant fallback ignores the clicked option Symptom
A shopper clicks one product option, then the fallback URL or selected variant changes that option.
Fix
Treat the clicked option as a hard constraint before scoring fallback variants.
Variant URLs and SEO state drift Symptom
Search params, selected options, canonical URLs, and visible product state disagree.
Fix
Create stable canonical and selected-option rules before indexing variant states.
PDP content is not owned by the content model Symptom
Product, support, or brand explanation copy requires code edits for normal merchandising changes.
Fix
Use product fields or structured metaobjects where merchant editability is a real requirement.
Issue category
Collections and discovery Collection pages, filters, sorting, product visibility, and catalog discovery.
Out-of-stock products disappear from the unfiltered collection Symptom
Shopify returns the products, but the storefront buffer stops before rendering them.
Fix
Separate API pagination state from app-local availability buffering.
Collection route mapping is incomplete Symptom
Legacy Liquid collection URLs, filters, or campaign paths are missing from the Hydrogen plan.
Fix
Map old routes, new routes, redirects, canonicals, filters, and sitemap entries together.
Migration breaks more than the template layer Symptom
Collection browsing, apps, analytics, redirects, and checkout assumptions move at once.
Fix
Name each breakage surface before implementation starts.
Issue category
Metaobjects and content models Structured content, page-specific sections, responsive copy, and merchant editability.
Desktop and mobile hero titles render differently Symptom
A content field mismatch changes responsive DOM behavior in production.
Fix
Normalize field comparison and verify the active metaobject entry before blaming CSS.
Page-specific sections are hardcoded Symptom
Campaign or product storytelling content requires developer releases for normal edits.
Fix
Move repeatable route-specific content into structured Shopify metaobjects when it needs merchant ownership.
Metaobjects are used as an unplanned CMS replacement Symptom
Content models grow without route ownership, validation, or Storefront API cost awareness.
Fix
Define fields, ownership, fallback behavior, and route usage before implementation.
Related links
Keep moving through this topic. 