Shopify's 128KB JSON Metafield Limit: Why Your Custom Build Might Silently Stop Saving
Shopify's metafield size limit changed in 2026: JSON metafields now cap at 128KB. Who gets hit, how to check your store, and how to migrate to metaobjects.
date
You changed the mega menu, saved it, and the storefront still shows the old version. Or the product configurator stopped accepting new options last month and nobody could say why. If your store relies on a custom build that keeps structured content in a single JSON metafield, there is a real chance you have hit the Shopify metafield size limit introduced in 2026, and the error never reached a human.
This piece covers what the limit actually is now (public information on it is contradictory), who gets caught, how to check whether your store is already over, and the sensible ways to restructure the data.
The actual numbers: 128KB for JSON, 64KB for everything else
Since API version 2026-04, Shopify caps JSON metafield writes at 128KB (131,072 bytes). Every other metafield type is capped at 64KB, and a few small types such as id and url sit lower still. The previous JSON limit was 2MB, so anyone storing a large blob has lost roughly 94% of their headroom. Shopify's own changelog post from February 2026 and the metafield limits documentation are the two sources worth trusting.
The reason you will find conflicting figures online is that Shopify first announced a 16KB cap for all types, then revised it upward after pushback on the developer forums. Several agency blog posts written in that window still describe 16KB as the current limit. It is not. If a developer quotes 16KB at you, they are reading stale coverage.
The grandfather clause, and why it is narrower than it sounds
Shopify grandfathered apps, not stores and not individual values. Any app, public or custom, that had created a JSON metafield definition before 1 April 2026 keeps the old 2MB limit on every store it is installed on. A new app, or a new custom integration built after that date, gets 128KB, unless Shopify approves an exception through its request form.
That distinction matters for merchants in two ways. First, your existing oversized values stay readable on every API version, so nothing vanishes from the storefront overnight. Second, the moment anything that is not grandfathered tries to update one of those values through API 2026-04 or later, the write fails. Shopify's docs put it plainly: existing values above the limit can be read but must be reduced before they can be updated. A store can look perfectly healthy right up until someone tries to edit the data.
Why a Shopify metafield limit exceeded error looks silent
Technically it is not silent. The Admin API returns a userError with the code TOO_LONG, and the message reads something like "Value exceeds the maximum size of 131072 bytes". The problem is where that error goes. A well-built app surfaces it in the merchant admin. A quick custom script written three years ago probably logs it nowhere and reports success. A headless storefront with a content sync job may skip the record and carry on.
We have seen the same pattern with Shopify's other platform deadlines, such as the blocked legacy script tags: the platform behaves exactly as documented, and the merchant finds out weeks later from a customer. If nobody owns the integrations that write to your store, nobody is reading those error responses.
Who actually hits the 128KB JSON metafield cap
Most stores never get near 128KB. A product spec table, a handful of FAQ entries or a size guide in JSON is a few kilobytes. The stores that get caught are the ones where a developer took the pragmatic shortcut of serialising an entire feature into one field. The usual suspects:
- Mega menus and navigation trees stored as one JSON object on the shop, with images, labels and links for every tier.Page-builder style layouts saved against a page or product, where every section and its settings live in one blob.Product configurators and customisers with large option matrices, pricing rules or 360-degree frame arrays.Headless storefronts using a shop-level metafield as a lightweight CMS for global content.Bulk import tooling that writes supplier data wholesale into a JSON field rather than mapping it to typed definitions.
There is a related read-side limit that catches configurators specifically. Shopify Functions, which power custom discount, delivery and payment logic, will not read a metafield value over 10,000 bytes. The value still exists and the Admin API still returns it, but the function receives null. If a discount rule quietly stopped applying, check this before anything else.
How to check whether your store is already over the limit
You do not need a vendor's tool for this. Query the Admin GraphQL API for metafields of type json on each owner type you use (shop, products, collections, pages, metaobjects) and measure the byte length of each value on your side. For a large catalogue, run it as a bulk operation and process the JSONL output. Anything over 131,072 bytes is a problem waiting for its next save. Anything over 65,536 bytes in a non-JSON type is the same.
While you are there, list every app and integration that writes to those fields and note the API version each one pins. A theme app block, a custom app and a third-party page builder can all write to the same metafield, and each needs checking separately. Grandfather status belongs to the app, so the same field can be writable from one tool and rejected from another.
- Export every json-type metafield and its byte size, grouped by namespace and owner type.Identify which app or script created each definition, and when.Confirm each writer's pinned API version and whether its definition predates April 2026.Flag any field over 100KB as a restructuring candidate even if it is not failing yet. Content only grows.
The fix: stop storing a database in a text field
The honest answer is that a 500KB JSON blob was never a good design, and the limit is forcing a correction many stores needed anyway. Three options, in rough order of preference.
Metaobjects. This is what Shopify built for structured content. Each definition supports up to 40 fields and up to one million entries, and entries can reference each other, so a mega menu becomes a set of menu-item entries with a parent reference rather than one nested object. Every entry has its own fields with their own limits, and the theme can read them directly in Liquid. One caveat: a Liquid loop can iterate a maximum of 50 entries at a time, so very large sets need pagination in the template.
List-type metafields. For simpler cases, a list of references or a list of single-line text values spreads the data across typed items rather than one string. Less flexible than metaobjects, but far less rework.
The Files API. For content that only needs to be fetched and rendered, never filtered or queried, upload it as a JSON file and store the file reference in the metafield. This suits large option matrices that storefront JavaScript consumes whole.
A proper Shopify metaobjects migration touches the theme, any custom apps and the content editing workflow your team uses, so it is not a one-afternoon job. But it is well scoped, and it usually leaves the store faster, because the storefront is no longer parsing hundreds of kilobytes of JSON on every page load. We cover the speed side in our piece on how too many apps slow a Shopify store down. Oversized metafields belong in the same conversation.
A metafield is a field. If you need a table, Shopify gave you metaobjects. If you need a file, it gave you Files. The new limit simply makes that distinction enforceable.What this means if you are planning a build
If you are commissioning a custom theme or a headless storefront now, ask the developer directly how structured content will be stored and what the per-field size ceiling is. A senior team will answer with metaobjects and typed definitions, not a JSON dump. That is how we approach Shopify theme design and development and headless ecommerce builds, partly because it is correct and partly because twelve years in this business has taught us that shortcuts always come due.
For stores already live, this is a data hygiene job rather than an emergency. Audit, restructure the fields that are over or close to the cap, and make sure someone is reading the error responses from every integration that writes to your store. It is the kind of unglamorous work that sits inside our Conversion Growth Retainer alongside testing and optimisation, because a storefront that quietly stops saving content is a conversion problem as surely as a slow checkout is.
If you suspect your store is affected and want a second opinion from a Glasgow team that does this work for brands across the UK and beyond, get in touch and we will run the audit.
Related articles
view all(01) Shopify Checkout Extensibility Deadline Passed: What to Audit on Your Store Now
The Shopify checkout extensibility deadline for Basic, Shopify and Advanced plans passed on 26 August 2026. Here is what was removed and what to check.
read article(02) Shopify Agentic Storefronts Explained: What Changed Since OpenAI Scaled Back Instant Checkout
OpenAI scaled back ChatGPT Instant Checkout. What Shopify Agentic Storefronts means for your store, which admin settings to check and what to ignore.
read article(03) Shopify's October 2026 Checkout Extension Deadline: Why Your App Deploys Are Blocked Right Now
Shopify CLI now blocks checkout UI extension deploys on API 2025-07 or earlier. How to check your version, what the Preact rewrite involves and where to start.
read articleStay ahead of the Shopify curve
Uncover Insights brings the latest Shopify trends, practical tips, and a look behind the scenes straight to your inbox.
We won't send you spam. Unsubscribe at any time.