What is the difference between a nil metafield and a blank metafield?

Nil means the metafield definition does not exist for this resource type — the namespace and key combination has never been defined. Blank means the definition exists but no value has been entered for this specific product or variant. In Liquid, both output empty strings. The {% if mf != blank %} check handles both cases safely.

Do metafields on all Shopify objects use the same .value pattern?

Yes. The access pattern is identical across products, variants, collections, customers, orders, pages, blogs, and locations. Always: resource.metafields.namespace.key.value. The only variation is in how .value is then used — scalar types output directly, rich text needs metafield_tag, reference types give you a Liquid object.

How do I display a list metafield?

List metafield .value returns a Liquid array. Iterate: {% assign tags = product.metafields.custom.extra_tags.value %}{% if tags != blank %}{% for tag in tags %} {{ tag }} {% endfor %}{% endif %}. For list.product_reference, .value returns an array of product objects you can call .title, .url, .featured_image on directly.

liquidMarch 22, 2026

Shopify Metafield Returns Blank — You Are Missing .value

You set up a metafield in Shopify Admin, reference it in Liquid, and the page renders blank where the value should be. No error, no warning — just nothing. In 90% of cases the fix is adding .value. A Shopify metafield in Liquid is not the value itself — it is a wrapper object. Outputting the wrapper directly renders nothing. This guide explains the .value requirement, the exceptions by type, and how to write defensive metafield code that handles nil safely.

Why .value is required for most metafield types

When you access product.metafields.custom.my_field in Liquid, you get a metafield object — a wrapper with properties: .value (the actual stored data), .type (the metafield type string), and .namespace. Outputting the wrapper directly with {{ product.metafields.custom.my_field }} renders the object's internal representation, which is blank for most metafield types. Adding .value accesses the actual stored data: {{ product.metafields.custom.my_field.value }}.

Which types require .value and which are exceptions

All scalar types require .value: single_line_text_field, multi_line_text_field, integer, decimal, boolean, date, date_time, url, color, weight, volume, dimension, rating, json. List types return a Liquid array via .value — iterate with a for loop. Rich text requires .value plus the metafield_tag filter: {{ mf.value | metafield_tag }}. Reference types (product_reference, variant_reference, file_reference, image_reference) return Liquid objects via .value that you can call methods on: {{ mf.value.title }}, {{ mf.value | image_url: width: 800 | image_tag }}.

Nil-safe metafield access pattern

Before outputting any metafield, verify it exists and has a value. Recommended pattern: {% assign mf = product.metafields.custom.my_field %}{% if mf != blank %}{{ mf.value }}{% endif %}. The blank check catches both nil (the metafield definition does not exist for this resource) and a metafield object with no value set. Using != blank is safer than != nil because a metafield with an empty value is not nil but is blank.

Debugging metafield output in Liquid

If a metafield is blank, debug by outputting the full object as JSON: {{ product.metafields.custom.my_field | json }}. This shows the complete metafield object including what .value contains and what .type is. If json output is null, the metafield is not set for this product. If it shows a type but .value is empty, the definition exists but no value has been entered in Shopify Admin for this specific product.

The fix: before and after

// CODE_COMPARISON

// BAD_CODE — before

1{%- comment -%} BAD: outputs blank — missing .value on wrapper object {%- endcomment -%}

2{{ product.metafields.custom.size_guide }}

4{%- comment -%} BAD: no nil check — blank page if metafield not defined {%- endcomment -%}

5{{ product.metafields.custom.care_instructions.value }}

7{%- comment -%} BAD: rich text without metafield_tag filter — outputs raw JSON {%- endcomment -%}

8{{ product.metafields.custom.rich_description.value }}

// SYPHIO_FIXED — after

1{%- comment -%} GOOD: .value with nil-safe blank check {%- endcomment -%}

2{% assign size_guide = product.metafields.custom.size_guide %}

3{% if size_guide != blank %}

4 <p>{{ size_guide.value }}</p>

5{% endif %}

7{%- comment -%} GOOD: rich_text type with metafield_tag {%- endcomment -%}

8{% assign rich_desc = product.metafields.custom.rich_description %}

9{% if rich_desc != blank %}

10 <div class="rich-text">{{ rich_desc.value | metafield_tag }}</div>

11{% endif %}

13{%- comment -%} GOOD: image_reference type {%- endcomment -%}

14{% assign extra_img = product.metafields.custom.extra_image %}

15{% if extra_img != blank %}

16 {{ extra_img.value | image_url: width: 800 | image_tag: alt: product.title }}

17{% endif %}

Frequently asked questions

What is the difference between a nil metafield and a blank metafield?: Nil means the metafield definition does not exist for this resource type — the namespace and key combination has never been defined. Blank means the definition exists but no value has been entered for this specific product or variant. In Liquid, both output empty strings. The {% if mf != blank %} check handles both cases safely.
Do metafields on all Shopify objects use the same .value pattern?: Yes. The access pattern is identical across products, variants, collections, customers, orders, pages, blogs, and locations. Always: resource.metafields.namespace.key.value. The only variation is in how .value is then used — scalar types output directly, rich text needs metafield_tag, reference types give you a Liquid object.
How do I display a list metafield?: List metafield .value returns a Liquid array. Iterate: {% assign tags = product.metafields.custom.extra_tags.value %}{% if tags != blank %}{% for tag in tags %}<span>{{ tag }}</span>{% endfor %}{% endif %}. For list.product_reference, .value returns an array of product objects you can call .title, .url, .featured_image on directly.

// SCAN_YOUR_CODE

Does your theme have this bug?

Paste your code. Syphio automatically detects and fixes this error and hundreds of others — in seconds.

Validate my Liquid →

Shopify Template Renders Blank? Misspelled {% endif %} and {% endfor %} Are the Cause→all_products[] Is an O(n) Full Catalog Scan — Here's the O(1) Replacement→Shopify Liquid: Single = in {% if %} Always Evaluates True — = vs == Explained→