September 23, 2026 · Muhammad Umar · More by Muhammad Umar
What Hydrogen's April 2026 Release Actually Breaks
Hydrogen 2026.4.0 bundled two breaking changes and a smaller metafield limit into a routine API bump. Here's what headless teams need to check.
Hydrogen's April 2026 release (v2026.4.0, shipped April 9) reads, at a glance, like the routine quarterly bump it partly is: Storefront API and Customer Account API move from 2026-01 to 2026-04. But bundled into that version bump are two changes Shopify itself flags as breaking, plus a tighter limit on JSON metafield writes — the kind of details that don't throw an obvious error until something downstream depends on the old behavior.
The API proxy is no longer optional
Before this release, createRequestHandler accepted a proxyStandardRoutes option that let a storefront opt out of the Storefront API proxy. That option is gone. The proxy is now always enabled, and Hydrogen's changelog is specific about the failure mode: if your load context doesn't include a storefront instance, the request handler now throws an error instead of logging a warning. Any custom request-handling setup that relied on the proxy being optional, or that tolerated a missing storefront instance in some code path, needs to be checked against this before upgrading, since the old behavior degraded gracefully and the new one doesn't.
Consent tracking moves server-side by default
The second breaking change is a bigger shift in mechanism: backend consent mode is now on by default, replacing the legacy _tracking_consent JS cookie with server-set cookies delivered through the Storefront API proxy. Hydrogen sets window.Shopify.customerPrivacy.backendConsentEnabled to true before the Customer Privacy API script loads, which tells the consent library to use the new server-set cookie mode instead of reading the old client-side cookie. Shopify's changelog notes the flag is installed via a window.Shopify property interceptor specifically so it survives the CDN's reset of window.Shopify = {} and stays readable before the full API is assigned. If anything in your storefront reads or depends on the _tracking_consent cookie directly, that dependency now points at a mechanism Shopify is actively deprecating.
Metafields and a more specific cart error
Storefront API 2026-04 also caps JSON-type metafield writes at 128KB. It's not retroactive: metafield values that existed before April 1, 2026 are grandfathered at the previous 2MB limit and stay fully readable on any API version, but new large JSON metafields written after that date will hit the smaller ceiling. Any headless storefront that writes structured JSON into metafields — configuration blobs, cached computed data, anything beyond a small object — is worth auditing against this before adopting 2026-04.
One smaller but genuinely useful change: cart operations that fail because a Cart Transform Function errors at runtime now return a distinct MERCHANDISE_LINE_TRANSFORMERS_RUN_ERROR code instead of the generic INVALID. If your storefront branches on cart error codes to show the buyer something specific, that's a case worth handling explicitly now that it's no longer indistinguishable from any other invalid-cart error.