The Five Liquid Limits Every Metaobject Catalog Hits

Storage limits aren't the ceiling you'll hit

Metaobjects have become the default way to model custom catalog content in Shopify themes — testimonials, size guides, lookbooks, structured FAQs. The storage limits are generous: Shopify's documentation sets each metaobject definition's capacity at up to 1,000,000 entries, and a list metafield can reference up to 1,024 metaobjects. Hit either ceiling and creating another entry fails outright with a MAX_OBJECTS_EXCEEDED error, or the list metafield simply has no room left. But those are storage limits. The documentation is explicit that Liquid rendering is governed by a separate, much smaller set of per-page-render limits — and those are the ones that actually constrain what a theme can display.

The five numbers that matter at render time

Per Shopify's metaobject-limits reference, a single page render is capped at:

• 50 entries when looping over metaobject_definition.values, or a list.metaobject_reference / list.mixed_reference metafield, without the paginate tag
• 250 entries per page once that loop is wrapped in {% paginate %}
• 1,000 unique entries of a single metaobject type loadable per page render, regardless of pagination
• 20 unique handles of a single metaobject type lookup-able with metaobjects.TYPE[handle] per render — including handles that don't match a published entry
• 50 distinct metaobject definitions reachable through the metaobjects object on any one page

Exceeding any of the per-type limits doesn't truncate silently — it renders a Liquid error instead of the entries. That's a meaningfully different failure mode than the storage-side MAX_OBJECTS_EXCEEDED: the page breaks outright for every visitor until the template is fixed.

Designing pagination around the limits, not around 50

Two other documented details compound this. First, checking size on a list.metaobject_reference or list.mixed_reference field returns the true total number of referenced entries, even when an unpaginated loop over that same field only returns the first 50 — so a naive length check can disagree with what the page actually renders. Second, metaobject_definition.values_count is subject to the platform's general 25,000-item count ceiling: beyond that, it reports 25,001 rather than an exact number, a behavior Shopify's own pagination-depth guidance confirms applies platform-wide, alongside the 250-item paginate cap (values above 250 are clamped, not rejected).

For theme and headless engineers, the practical takeaway is to design around the 1,000-entry, 20-handle, and 50-definition ceilings from the start, not after a page assembling many individual metaobject references by handle quietly breaks. A reference-heavy page can hit the 20-handle limit well before it comes close to any storage limit, with no warning until the Liquid error appears.

Sources

• Metaobject limits
• Limit pagination depth to improve query performance
• Theme limits