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 doesn't match the definition's type — a number in a text field or vice versa triggers "Validation failed: Value is not using the expected value_type: 'string'".
- The metafield is a rich text type — rich text expects structured JSON, so pasting plain text fails even when the ID and definition are correct.
- 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.
Create the definition BEFORE you import
This is the single most common failure. 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.
Store owners who "can't get metafields to import no matter what" almost always have a header/definition mismatch: the definition uses one key, the CSV column references another.
- Settings → Custom data → Products (or Variants) → Add definition.
- 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.
The value_type error, decoded
"Validation failed: Value is not using the expected value_type: 'string'" means the definition's content type and your cell value disagree. It usually appears line-by-line ("Line 2-7: Validation failed…") because every row carries the same wrong format.
Fix the values, not the definition — changing a definition's type after products reference it causes bigger problems. Strip stray quotes, currency symbols, or JSON fragments from plain-text fields, and make sure number fields contain only digits and a decimal point.
Rich text and variant metafields: know the limits
Rich text metafields expect Shopify's structured JSON format, not plain prose. Plain text in a rich text column is the classic "my metafield ID is correct, I've checked a hundred ways, it still won't import" scenario. If you don't need formatting, a multi-line text definition is far more CSV-friendly.
Variant-level metafields are also less reliable through the native importer than product-level ones. For large catalogs with complex variant metafields, a dedicated import app (Matrixify is the usual pick) is currently the dependable route — the native CSV works best for product-level text, number, and boolean metafields.
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 and EcomCSVFix cleans headers, handles, encoding, and booleans — so a failed import can only be the metafield mapping, not ten other things.
- Metafield-specific validation (definition checklist, value-type checks, rich text formatting) is in development — the cleaner flags unrecognized columns today.
Before and after
Handle,Title,metafield:care
mug-blue,Blue Mug,"30"Handle,Title,Care Instructions (product.metafields.custom.care_instructions)
mug-blue,Blue Mug,"Hand wash only"Fix it automatically in 30 seconds
Upload your CSV, let EcomCSVFix repair the broken rows, then download a Shopify-ready file.
Free for up to 5 files/month. No credit 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?
Rich text values must be Shopify's structured JSON, not plain text. Either format the JSON correctly or switch the definition to multi-line text if you don't need rich formatting.
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.