How to Fix Shopify Metafield Import Errors
A Shopify metafield import error usually means one of four things: the column header doesn’t match the metafield’s namespace and key, the metafield type can’t be imported by CSV, a value doesn’t match the type’s format, or a value breaks a rule in the metafield’s definition. Reference fields add one more common cause, which is entering a display name where Shopify expects a handle.
The fix depends on which of these you’re facing. Error messages often point only to a line number, so it helps to know what each symptom means before editing your file.
Why Metafield Imports Fail: Quick Diagnosis
Match what you’re seeing to the table below, then jump to the section that covers the fix. Most problems fall into the first two or three rows.
| What you see | Likely cause | Where to fix it |
|---|---|---|
| The import finishes, but metafield values don’t appear | The column header doesn’t match the metafield’s namespace and key | Fix the column header |
| Variant metafield values never import | Variant metafields aren’t supported in the product CSV | Check whether the type can be imported |
| File, rich text or JSON values don’t import | The metafield type isn’t supported for CSV import | Check whether the type can be imported |
| “Validation failed” errors on specific lines | A value doesn’t match the type’s format or the definition’s rules | Fix the values in your file |
| “Value require that you select a metaobject” | A reference value uses a display name, or the metaobject entry doesn’t exist | Fix reference and metaobject values |
| “Update the invalid values, then save again” in the bulk editor | A metafield value fails validation | Fix the values in your file |
| Customer metafields fail to import | The type isn’t one of the few allowed in customer CSVs | Customer and app metafield errors |
| “You do not have permission to modify the metafield” | An app owns the metafield | Customer and app metafield errors |
Before changing anything, find one product where the metafield already has a correct value, or add one by hand in the admin. Exporting that product gives you a working example of both the header and the value format, which is the fastest way to see what your file is doing differently.
Fix the Metafield Column Header
Shopify only recognizes a metafield column when its header follows a set pattern: Name (product.metafields.namespace.key). The name in front is optional, so product.metafields.namespace.key also works. For example, a fabric metafield could use the header Fabric (product.metafields.shopify.fabric).
The namespace and key must match the metafield exactly. To find them, go to Settings > Metafields and metaobjects (labeled Custom data in some admins), choose Products and open the metafield definition. A small difference, such as size_chart versus sizechart, means Shopify can’t connect the column to the metafield.
The most reliable way to get headers right is to copy them from an export. Once a product metafield has a definition, it’s included in your product CSV exports, so exporting a few products gives you correctly formatted headers you can paste into your import file.
Check Whether the Metafield Type Can Be Imported
Not every metafield type can be imported through Shopify’s product CSV. If the type isn’t supported, no amount of reformatting will make the value import. Shopify lists these types as supported for bulk CSV import and export:
| Group | Supported types |
|---|---|
| Text | Single line text, multi-line text |
| Numbers | Integer, decimal, and lists of each |
| Dates | Date, date and time, and lists of each |
| Measurements | Dimension, volume, weight, and lists of each |
| Other values | True or false, color, money, URL, and lists of colors and URLs |
| References | Product references, lists of product references and lists of metaobject references |
Types missing from that list, such as file references, rich text and JSON, can’t be filled through the product CSV. Variant metafields aren’t supported for product CSV import or export either, even when their type is on the list.
For these cases, use the bulk editor instead. Select products on the Products page, click Bulk edit and add metafield columns through Columns. For variant metafields, use the variant bulk editor and add the metafield columns there.
Fix the Values in Your File
Once the header and type are right, the remaining errors come from the values themselves. Shopify validates each value against the metafield’s type and against any rules set in its definition, and rejects rows that fail either check.
Match the format each type expects
Each metafield type accepts values in a specific format. The table below covers the formats that cause the most trouble in import files:
| Type | Expected value | Common mistake |
|---|---|---|
| Date | ISO 8601, such as 2026-10-10 | Excel converting it to 10/10/2026 |
| Date and time | ISO 8601 with the time in UTC | Local time without a time zone |
| Color | Hex code in #RRGGBB format, such as #1A2B3C | Color names such as “navy” |
| Integer | Whole numbers only | Decimals or thousands separators |
| Decimal | Up to 9 digits after the decimal point | Currency symbols or units in the cell |
| Single line text | Plain text with no line breaks | Text pasted with hidden line breaks |
| URL | A full address including the scheme, such as https:// | Addresses starting with “www.” |
| Money | A number in your store’s currency | A different currency |
| Any list type | Values separated by semicolons, such as #ff00cc; #cc0000 | Commas or line breaks between values |
Measurement types such as weight and dimension need both a number and a unit. Because the exact CSV notation is easy to get wrong, copy it from an exported product that already has a value rather than typing it from scratch.
Excel causes many of these problems on its own. It reformats dates, drops leading zeros and can change long numbers into scientific notation. To prevent this, format metafield columns as Text before pasting values, and save the file as CSV UTF-8 so special characters survive.
Use handles for references and metaobjects
Reference metafields point to other records, so Shopify needs an identifier it can look up, not a label. For product and metaobject references, enter the record’s handle or its GID, such as gid://shopify/Metaobject/123. Separate multiple references with semicolons, for example blue; red.
The error “Value require that you select a metaobject” usually appears when a cell contains the metaobject entry’s display name, or when no entry with that handle exists. For example, if a size chart entry is titled “Men’s Shirts” but its handle is mens-shirts, the cell must contain mens-shirts.
The referenced records must also exist before you import. Check your metaobject entries in the same Settings area, confirm each has the handle your file uses, and create any missing entries first. The same applies to product references: the product a cell points to must already be in your store.
Check the definition’s validation rules
A value can match its type and still fail because of a rule set in the metafield definition. Open the definition in Settings and look for these restrictions:
- Preset choices: Single line text can be limited to a list of choices, and the value must match one of them exactly.
- Length and pattern rules: Multi-line text can have minimum and maximum lengths or a regular expression the value must match.
- Number ranges: Integer and decimal fields can have minimum and maximum values.
- Domain restrictions: URL and link fields can be limited to specific domains.
- Currency: Money values must use your store’s currency.
If many rows fail on the same rule, decide whether the data or the rule is wrong. Sometimes the right fix is to correct the values, but a preset choice list that’s missing a valid option needs updating in the definition instead.
Customer and App Metafield Errors
Customer metafields follow stricter rules than product metafields. In a customer CSV, only boolean, date, date and time, integer, decimal and single line text metafields can be imported and exported. Their headers use the format customer.metafields.namespace.key, so a customer import fails for other types or for headers copied from a product file.
Metafields created by apps can raise permission errors. Some apps create metafields that only they can modify or delete, so an import from another tool returns errors such as “You do not have permission to modify the metafield.” In that case, update the values through the app that owns the metafield, or use a different metafield your import tool is allowed to write.
Import apps can also report metafield problems differently from Shopify’s own importer. Some create the product or order first and add metafields in a separate step, so a record can import successfully while its metafields fail. If values are missing after an app import, check the app’s import log for metafield warnings.
Conclusion
Most metafield import errors come down to a header, a type or a value that doesn’t line up with how Shopify defines the metafield. Working from an exported example and checking the definition’s rules turns a vague line-number error into a quick fix. We hope this guide helps you resolve your metafield import error and keep custom data flowing into your store. If you manage store data imports regularly, you can explore Bulkflow.
