Quick answer
Modern Shopify metafields usually need `.value` in Liquid. If a metafield shows as an object, prints blank, or behaves differently than an older store, check the resource, namespace, key, type, storefront access, and whether the metafield is legacy/deprecated.
Symptom
You added a metafield in admin or by API, but Liquid prints nothing, prints a strange object, or prints a value differently than expected.
Most likely causes
- Missing `.value`. Modern metafield objects often need `{{ product.metafields.namespace.key.value }}`.
- Wrong resource. Product, variant, collection, shop, customer, and company metafields are accessed from different objects.
- Wrong namespace/key. `custom.size_chart` and `my_fields.size_chart` are different.
- Deprecated metafield type. Older metafields can return values directly, while newer types return metafield objects.
- Storefront access not enabled. Some metafields exist in admin but are not exposed where Liquid needs them.
- Snippet variable scope. Inside snippets, the product object may have a different variable name.
Quick checks
- Print the object with `| json` during debugging.
- Try `.value` after the metafield path.
- Confirm the namespace and key in Settings → Custom data.
- Confirm the metafield belongs to the object you are rendering.
- Confirm a value is assigned on the actual product/variant/shop/company.
- Check whether the metafield definition is exposed to the storefront where needed.
Theme, app, or code checks
- For products: `product.metafields.custom.key.value`.
- For variants: use the selected/current variant object, not always the product object.
- For shop metafields: `shop.metafields.custom.key.value`.
- For references/files/lists, the value may need loops or reference-specific handling.
- If a snippet receives a custom variable, use that variable instead of assuming `product` exists.
When to stop guessing
Stop guessing and reduce the problem to one known product with one known metafield. If that value prints in the main product template but not in a snippet, it is probably scope. If it does not print anywhere, it is probably path, type, value, or access.
Prevention checklist
- Name namespaces and keys consistently.
- Document every metafield used by the theme.
- Use modern metafield definitions instead of legacy ad hoc fields.
- Avoid creating metafields by API without confirming the type and storefront access.
- Add temporary debug output on a duplicate theme, not live.