Why Does a Shopify File Metafield Return a GID Instead of a Download URL?

A product has a PDF manual or downloadable document stored in a Shopify metafield, but rendering the field produces a gid://shopify/GenericFile/... value instead of a usable link.

The likely cause

A file_reference metafield points to a Shopify file object rather than storing the CDN URL as ordinary text.

The confirmed Community fix

Resolve the metafield’s .value first, then access the resulting file object’s .url property.

{% assign manual = product.metafields.custom.manual.value %}

{% if manual != blank and manual.url != blank %}
  <a href="{{ manual.url }}" target="_blank">
    Download manual
  </a>
{% endif %}

Admin path

1. Go to Settings > Custom data > Products.
2. Confirm the definition is a File/file-reference metafield.
3. Open the product and confirm a file is actually selected and saved.

Sources

• Shopify Developer Docs: generic_file