Shopify metafield CSV repair
Shopify Metafield CSV Import: Why It Fails
Metafields CAN be imported through Shopify's product CSV — but only if the metafield definition exists first and the column header matches it exactly. Miss either and Shopify skips the data, often without an error.
What causes this error
- No metafield definition exists in Settings → Custom data, so Shopify has nowhere to map the column and silently ignores it.
- The column header doesn't match the definition's exact namespace and key — metafield columns look like "Care Instructions (product.metafields.custom.care_instructions)", and any mismatch fails the mapping.
- The value does not meet the definition type or validation rules. For example, a number field cannot accept arbitrary words. A numeric-looking value can still be valid text.
- The metafield is a rich text type — rich text is not in Shopify's list of CSV-supported metafield types. Set it in admin or via an app; use a multi-line text definition if you don't need formatting.
- List-type metafields are formatted with the wrong separator, so the whole cell is rejected or stored as one value.
- The column isn't on Shopify's default import template, so it was added by hand with a guessed header format.
First, separate a CSV problem from a store-definition problem
EcomCSVFix checks header formatting and patterns in the values in your file. It does not read your store's definitions or know which validation rules you configured. A clean report cannot certify that a value meets those rules.
For product metafields, export one product with a known good value and compare its namespace, key, and value format with your CSV. Product CSV import does not support variant metafields. For those, use Shopify's variant bulk editor or a suitable app.
Download a two-product metafield CSV example. Create a matching product definition for custom.care_instructions first. This is sample product data, not an export from your store.
Shopify's product CSV documentation describes supported types and accepts both a named header and a bare product.metafields.namespace.key header.
Create the definition BEFORE you import
Start by checking the definition. Shopify's importer maps metafield columns to existing definitions — it does not create definitions from your CSV. If the definition doesn't exist when the import runs, the column is ignored with no error message.
Check for a header/definition mismatch: the definition uses one key, the CSV column references another.
- Settings → Custom data → Products → Add definition. Variant definitions do not make variant metafields importable through product CSV.
- Choose the content type carefully — it's what your CSV values will be validated against.
- Copy the namespace.key shown on the definition into your column header.
some metafields have validation errors
When Shopify shows this message — or the closely related wording "some metafield values have validation errors" — it is a rollup, not a single root cause. The import results usually list more specific failures per line or per field underneath.
Open those details and match each line to the specific errors below: value type mismatches, owner subtype mismatches, and missing file sources. Fix those fields, then re-import — the rollup clears once the underlying values pass.
Validation failed: Value is not using the expected value_type
This means the cell value does not match the content type on the metafield definition. Shopify validates every imported value against that type: a single-line or multi-line text field expects a string, number fields expect bare digits (and an optional decimal), and booleans expect true/false.
Fix the CSV values to match the definition. Changing a definition's type after products already reference it creates wider breakage. Strip currency symbols and thousands separators from number fields, use bare true/false for booleans, and keep plain text as strings. It often appears line-by-line because every row carries the same wrong format. Rich text is a different limit — it is not in Shopify's CSV-supported type list, so putting JSON in the cell is not a CSV fix. See rich text and variant metafields.
owner subtype does not match
This error means the metafield is being written to a resource that does not match the definition's owner constraints. The usual case is a product-level definition applied on a variant (or the reverse). Shopify also uses subtype constraints for category-limited product metafield definitions, so a definition scoped to one product category can reject products outside that category.
In Settings → Custom data, open the definition and confirm which resource it belongs to (Products vs. Variants, for example) and whether any category constraints are set. Align the CSV column with that owner: product metafield headers use the product.metafields… form on the product row. Do not push a product-owned metafield through a variant-only update, and do not invent a variant metafield column for a definition that lives under Products.
file original source missing from the product files input
Shopify expected a fetchable file or image source and did not get one. Merchants most often see this when an Image Src, Variant Image, or file-related column has a blank cell, a local filename instead of a URL, or a link that is not a public HTTPS file Shopify can download.
Use a full, publicly accessible HTTPS URL that points directly at the file — not a login-walled Drive or Dropbox preview page. If you are not importing images or file data on this run, remove the empty file/image columns rather than leaving blank source cells. For a file-reference metafield, export a product that already has the file set and mirror that column format exactly; do not guess the header or paste a filename without a source URL.
Rich text and variant metafields: know the limits
Rich text is not in Shopify's list of CSV-supported metafield types. The cleaner flags HTML in metafield cells; it will not convert prose or HTML into rich text. Set rich text in admin or via an app. If you don't need formatting, a multi-line text definition is the CSV-friendly option.
Variant-level metafields cannot be imported through the product CSV at all — Shopify's docs say so. The cleaner flags variant.metafields.* columns. For those, use the variant bulk editor in Shopify admin, or a dedicated import app.
How to fix it
Option A: fix it manually
- Create the metafield definition first: Settings → Custom data → Products → Add definition. Note the exact namespace and key (e.g. custom.care_instructions).
- Export one product that already has the metafield set in admin — the export shows you the exact column header format Shopify expects.
- Copy that header into your import file verbatim, including the namespace.key in parentheses.
- Check every value against the definition's type: text stays text, numbers are bare numbers, true/false for booleans.
- Import, then spot-check one product in admin — metafield mapping failures are often silent, so don't trust the success message alone.
Option B: fix it automatically
- Upload your CSV. EcomCSVFix detects metafield columns and repairs malformed headers to Shopify's NAME (product.metafields.namespace.key) form.
- It infers each metafield column's value type from the values themselves and flags rows that break that shape — currency symbols stripped from numbers, list separators normalised to Shopify's "; ".
- Variant metafield columns (variant.metafields.*) are flagged: they cannot be imported through the product CSV. Use the variant bulk editor in Shopify admin.
- The report lists every namespace.key that needs a matching definition in Settings → Custom data → Products before import. Shopify maps to existing definitions and does not create them.
- Rich text is not in Shopify's list of CSV-supported metafield types. Set rich text in admin or via an app — the cleaner will not convert it.
Before and after
Handle,Title, Care Instructions (product.metafields.custom.care_instructions)
mug-blue,Blue Mug,Hand wash onlyHandle,Title,Care Instructions (product.metafields.custom.care_instructions)
mug-blue,Blue Mug,Hand wash onlyCheck your CSV before importing
Upload your CSV, review the formatting fixes and warnings, then download. Store-specific problems may need changes in Shopify.
Free preview up to 500 rows. No account or card.
FAQ
Can Shopify import metafields via CSV natively?
Yes, for product-level metafields with an existing definition and an exactly matching column header. It isn't on the default template, which is why many guides say it's impossible — export a product that has the metafield set to see the real column format.
Why does my metafield column import with no error but no data?
The column header didn't map to a definition, so Shopify ignored it. Silent skipping — not an error message — is the default behavior for unrecognized columns.
Why won't my rich text metafield import from CSV?
It isn't in Shopify's list of CSV-supported metafield types. Set rich text in admin or via an app, not in the CSV. If you don't need formatting, a multi-line text definition is the CSV-friendly option.
Do I need Matrixify to import metafields?
Not for product-level text, number, or boolean metafields — the native CSV handles those once definitions exist. Matrixify or similar apps earn their fee on variant metafields, rich text at scale, and full-store migrations.
Can metafield columns slow down my import?
Large imports with many metafield columns have been reported to run slower. If a big import stalls, try splitting metafield updates into a separate, smaller file.