Altera shows a code such as ABC001 with each error or warning. This article explains the codes for this area of the app and how to resolve them. For codes from other areas, see Error and warning codes.

Error and warning codes related to metafield values, operations, and conversions during imports.

The value provided for a metafield could not be saved to Shopify because it doesn't match the expected format or validation rules for that metafield. This commonly happens when:

To resolve this issue, check that the metafield value conforms to the requirements of its definition in your Shopify store. You may need to view the metafield definition in Shopify admin to verify the expected type and format.

This is a warning, not an error. The product was successfully imported, but one or more category metafields were skipped because they don't apply to the product's category.

Shopify's category metafields (also called "category attributes") are special metafields that are only valid for products in specific categories. For example, a "Gender" category metafield only applies to apparel categories, not to categories like "Vehicles & Parts" or "Electronics".

When Altera detects that a category metafield doesn't match the product's category, it:

Common scenarios:

How to resolve:

This is a warning, not an error. The product was successfully imported, but a metafield reference value could not be resolved to an existing object in your store.

This commonly occurs with:

Common causes:

How to resolve:

The app could not find the metafield value for the color Category Metafield (shopify.color-pattern). This is because the color's metaobject entry does not already exist on the store and is not in Shopify's list suggested colors.

If you are migrating products from another store, the best fix it to export the metaobject entries from the source store (using the Metaobjects export) and import those metaobject entries to the destination store first. Then import the products that reference them.

Shopify stores rich text metafields not as HTML but in a custom JSON format. When you import HTML content into a rich text metafield, Altera attempts to convert it to Shopify's rich text JSON format for you. However, if the HTML is invalid or contains elements that cannot be converted, the conversion may fail.

Common causes:

How to fix this:

You are trying to modify a metafield that belongs to a protected namespace. Certain namespaces are reserved by Shopify or other apps and cannot be modified through third-party applications like Altera.

Common protected namespaces include:

For Shopify standard metafields (shopify--* namespaces):

Altera will try to activate the standard definition automatically before importing. If activation fails, the definition may already exist on the store with write access restricted to another app. To resolve:

For namespaces owned by another app (not Shopify), remove the protected metafields from your import file. These must be managed through the app that owns them.

This code has been replaced by IMP007.

The value provided for a boolean metafield could not be interpreted as true or false. Boolean metafields only accept values that clearly indicate true or false.

Accepted values:

How to fix this:

Update the cell in your import file to use one of the accepted values above (e.g. true or false).

The value provided for a money metafield could not be parsed. Money fields accept several formats.

Accepted formats:

How to fix this:

Update the cell in your import file to use one of the accepted formats above. Make sure the currency code is a valid three-letter ISO 4217 code (e.g. USD, EUR, CAD). If no currency code is provided, the shop's default currency is used.

The value provided for a weight, dimension, or volume metafield could not be parsed. The metafield was skipped and the existing value on the object (if any) was left unchanged.

Accepted formats:

How to fix this:

Update the cell in your import file to use one of the accepted formats above. For weight use g, kg, lb, or oz. For dimension use mm, cm, m, in, or ft. For volume use ml, l, gal, or qt.

A metafield column header includes a type annotation in square brackets that isn't a recognized Shopify metafield type. For example, Metafield: custom.width [width] - width is not a valid type (the matching type is dimension).

The invalid type is ignored. If a metafield definition exists on the store for that namespace and key, the defined type is used. Otherwise the value is imported as a single line text field.

How to fix this:

Update the column header to use a valid type, or drop the [...] part entirely and let Altera look up the type from the metafield definition. Common types include single_line_text_field, number_integer, number_decimal, boolean, date, date_time, dimension, weight, volume, color, rating, url, json, and *_reference variants.

A metaobject_reference or list.metaobject_reference metafield value isn't in a format that Altera can resolve to a metaobject entry. References must be in type.handle format (e.g. shoe_material.canvas) or a Shopify GID (e.g. gid://shopify/Metaobject/123456789). The same format applies to disclosure references (disclosure_reference, list.disclosure_reference, and product_taxonomy_disclosure_reference), which also point to metaobject entries.

A bare handle like canvas will not import because Altera can't always tell which metaobject definition it belongs to.

How to fix this:

Update the cell to include the metaobject type as a prefix, separated by a period. For example, change canvas to shoe_material.canvas. For list values, use a comma-separated list of references in the same format (e.g. shoe_material.canvas, shoe_material.suede). Alternatively, use the full Shopify GID of each referenced metaobject entry.

A metafield column header specified a type (e.g. Metafield: mm-google-shopping.condition [string]) that doesn't match the type of the metafield definition set up on the store for that namespace and key (e.g. single_line_text_field). Shopify rejects writes whose type disagrees with the definition, so Altera automatically uses the definition's type instead and imports the value.

This commonly happens when re-importing an export of legacy metafields - such as the mm-google-shopping (Google sales channel) fields - whose stored type is Shopify's deprecated string type while the definition uses the modern single_line_text_field type.

How to fix this:

No action is required - the metafield is imported using the correct type from the definition. To avoid the warning, update the column header to use the definition's type, or remove the [...] type annotation entirely and let Altera resolve the type from the definition.

A metafield filter was set up on an export, but its conditions did not match any of the metafields found on the store. As a result, the export contains no metafield columns for that group. This usually means the namespace or key in the filter condition is mistyped.

How to fix this:

Check the namespace and key values in the export's metafield filter. Use the bare values, for example namespace shopify and key cigar-body, or shopify.cigar-body for "Namespace and key". Altera automatically ignores a pasted Metafield: prefix and a trailing [type] suffix (e.g. [list.metaobject_reference]), but the namespace and key themselves must match the metafield exactly. Note that a metaobject type like shopify--cigar-body (with two dashes) is not the metafield namespace/key - the corresponding metafield is shopify.cigar-body.

A row of a Metafields sheet (one metafield per row, see Import metafields as a sheet) could not be used because it is missing something Altera needs to find the owner or the metafield:

How to fix this: fill in the column the message names and import the row again.

The Owner Handle of a Metafields sheet row matched nothing in your store: no product, collection, page, blog, or article with that handle, no variant with that title, no customer with that email, no company, location, order, or draft order with that name.

How to fix this: check the handle spelling (handles are case-sensitive), or use the Owner ID column with the item's Shopify ID. If the item is created by another sheet of the same import, put that sheet before the Metafields sheet, or leave the row to the Import Generated Metafields step, which runs after every sheet.

The metafield import template you tried to download no longer has a file attached. This happens when the file has been removed, for example after a data-retention cleanup. Create a new template from the Tools page and download that instead.

Previous code: MSF001.

Error and warning codes for importing and exporting metafield definitions.

The metafield definition could not be deleted. This may be because the metafield definition was already removed.

Certain namespaces like shopify and shopify--discovery--product_search_boost are protected namespaces that belong to Shopify proper. Third-party apps are not allowed to update these metafield definitions through the API. This often occurs when trying to import metafield definitions for Shopify Product Category Metafields. Unfortunately at this time those still need to be created manually within the Shopify admin.

Your metafield definition import is missing one or more required columns. The following columns must be present in your spreadsheet:

Add the missing columns to your spreadsheet and try again.

When every row uses the DELETE command, Type: Name is not required. A delete file only needs an ID column, or the Namespace, Key and Owner Type columns, to identify the definitions to remove.

The column for specifying the metafield type should be named 'Type: Name', not just 'Type'. Please rename this column in your spreadsheet before importing.

The first row of your import is missing a 'Type: Name' value. This field specifies the metafield data type (e.g. single_line_text_field, number_integer, boolean) and is required when creating new metafield definitions. If your definition spans multiple rows (for example, to include validation rules), only the first row of each group needs a 'Type: Name' value. Existing definitions being updated do not need this value since the type cannot be changed after creation.

The first row of your import is missing an 'Owner Type' value. The owner type tells Shopify which object this metafield definition belongs to and is required to both create and look up definitions. If your definition spans multiple rows, only the first row of each group needs an 'Owner Type' value.

See the Owner Type reference for all accepted values.

The owner type is not one Shopify recognizes, so the definitions cannot be looked up or saved. This applies to the Owner Type column in a metafield definitions import and to the owner_type parameter on the metafield definitions API. The message lists every accepted value.

To resolve this:

Capitalization and spacing do not matter, so product variant and PRODUCTVARIANT both work.

On an import, rows that include an ID are matched on that ID, so the owner type is not needed. Those rows report this as a warning, ignore the unrecognized value, and continue. If the ID does not match an existing definition, the row needs a valid owner type after all, and the warning becomes an error.

One of the Access: Admin, Access: Storefront, or Access: Customer Account columns contains a value that Shopify does not accept, so the row was not imported. The message lists the accepted values for that column.

To resolve this:

See the Metafield Definition Fields reference for details on each column.

Shopify rejected one or more of the Capability: ... settings for this metafield definition. The rest of the definition was saved, but the capability settings were skipped. The message includes the reason Shopify gave.

Common causes:

Leave a capability cell blank to keep the definition's current setting.

Shopify rejected the Access: ... settings for this metafield definition. The rest of the definition was saved, but the access settings were skipped. The message includes the reason Shopify gave.

The most common cause is setting Access: Admin on a definition whose namespace the app does not own (such as custom). Shopify only lets an app restrict admin access on its own app-reserved namespaces, so leave the Access: Admin cell blank for other namespaces.

Error and warning codes that occur when dealing with metaobject imports and operations.

A metaobjects file is missing the Definition: Handle column, or the column exists but has blank cells. Every metaobject row needs the handle of the definition it belongs to, so the file cannot be analyzed without it.

Add a Definition: Handle column and fill it with the definition handle for every row, then upload the file again.

The metaobject definition type is required for metaobject imports and cannot be empty. The 'Definition: Handle' column specifies which metaobject definition the imported data should use.

Make sure your import file includes a 'Definition: Handle' column, and that the first row of every metaobject has a value in it. Rows with a blank definition handle are reported as failed, and the rest of the import continues.

The metaobject definition with the specified type could not be found in your Shopify store. This typically occurs when the metaobject definition doesn't exist or the type name is incorrect. Verify that the metaobject definition exists in your store and that the type name matches exactly.

A field key in your import file does not match any field in the metaobject definition. The field was skipped during import.

Metaobject fields have both a name (displayed in the Shopify admin) and a key (used for the API). When you rename a field in the admin, the display name changes but the key stays the same. Altera matches fields using the key, not the display name.

To find a field's key: open the metaobject definition in Shopify admin, click on the field to expand it, and look for the Key value shown at the bottom of the field settings.

The row used the REPLACE command, which deletes the existing metaobject and creates a new one from the row. The delete succeeded, but Shopify rejected the new metaobject, so the metaobject is no longer on the store.

Before it deletes, Altera checks the row for problems it can detect itself (a missing definition, field values that can't be formatted, and so on) and fails the row with the metaobject intact. This error only appears when Shopify rejects something after the delete, for example a field value that fails the definition's validations.

To resolve this, fix the problem in the message and import the row again with Command set to MERGE, which creates the metaobject if it is missing. The original metaobject's ID is gone, so metafields that referenced it need to be set again.

The metaobject import template you tried to download no longer has a file attached. This happens when the file has been removed, for example after a data-retention cleanup. Create a new template from the Tools page and download that instead.

Previous code: MOSF001.

Error and warning codes that occur when dealing with metaobject definition imports and operations.

The metaobject definition you are trying to delete cannot be found in your Shopify store. This may be because it was already deleted or because the identifier (ID or type) provided in your import is incorrect.

The 'Type' column is required for metaobject definition imports and cannot be empty. This column specifies the type identifier for the metaobject definition, which is used to identify and create the definition in Shopify. Make sure your import file includes the 'Type' column with valid type names for all metaobject definitions.

You are trying to create or modify a metaobject definition that belongs to Shopify (types starting with "shopify--"). These are system-managed metaobject definitions that cannot be created or modified through the API.

Product category metaobject definitions (like shopify--size, shopify--color, shopify--material) are an exception - Altera can enable these for your store if they don't already exist. These are automatically handled during import.

Other Shopify-owned metaobject definitions (such as those for the Knowledge Base) cannot be created through the API. These must already be enabled on your store before you can import metaobjects that reference them. To enable them, go to your Shopify admin and enable the corresponding feature (e.g., install the Knowledge Base app to create its metaobject definitions).

If you're importing Shopify-owned metaobject definitions that are not product category types, please remove them from your import file or ensure the feature is already enabled on your store.

A field definition in your import references another metaobject definition that doesn't exist in this store. This occurs when importing metaobject definitions that have fields with metaobject_reference or mixed_reference types that require validations pointing to other metaobject definitions. The referenced metaobject definition must exist in the destination store before you can import the definition that references it. Import the referenced metaobject definitions first, then retry importing this definition.

You are trying to delete a standard Shopify metaobject definition (a type starting with "shopify--"). These are system-managed metaobject definitions that cannot be disabled or deleted through the API. Only custom metaobject definitions can be deleted through imports.

An error occurred while trying to enable a standard metafield definition for a Shopify product category. This typically happens when the definition key is invalid or the definition is already enabled. Check the error message for specific details about what went wrong.

You are deleting a metaobject definition. This action will also permanently remove all metaobject entries associated with that definition. For example, if you delete a "testimonials" metaobject definition, all testimonial entries will also be deleted from your store.

We recommend exporting your metaobjects as a backup before proceeding with the delete operation.

You are replacing a metaobject definition. The REPLACE command will delete the existing definition and recreate it, which will also permanently remove all metaobject entries associated with that definition.

We recommend exporting your metaobjects as a backup before proceeding with the replace operation. Consider using the MERGE command instead if you only need to update specific fields of the definition without losing existing entries.

The metaobject definition was created successfully, but a field validation referencing another metaobject definition could not be applied. This can happen when the referenced definition does not exist or when there is an API error during the second pass of validation application.

The definition exists but the reference constraint is missing. You can add the validation manually in Settings > Custom data > Metaobjects, or re-import the definition after ensuring the referenced metaobject definition exists on the store.

A row used the NEW command, but a metaobject definition with the same type already exists on the store. The NEW command only creates definitions and never changes existing ones, so the row was skipped.

How to fix this:

Error and warning codes that occur when importing or exporting store translations.

No translation rows were found in the input data for this resource. Each row should represent a translation with a Field (key), Locale, and Translated content.

The Shopify resource GID could not be parsed. GIDs should be in the format gid://shopify/ResourceType/id (e.g., gid://shopify/Product/8079393521850). Verify the GID is correct and try again.

The GID in the row points to a Shopify resource type that does not support translations, so Altera cannot look up its translatable content. The message names the resource type that was found.

Check the ID value in the row. Translations are supported for types such as products, collections, pages, articles, blogs, menus, metafields, metaobjects, and theme content. See the translation fields reference for details.

The content digest could not be obtained for a translation field. This can happen when:

The translation for this field will be skipped. To fix this, ensure the field has a value in the default language on the target store first, then re-import the translation. Alternatively, include the 'Default content' column in your import file with the current default value.

The 'Default content' column was not found in your import file. The import will still work, but will be slower because Altera needs to fetch the content digest from Shopify for each resource.

Recommendation: Include the 'Default content' column in your import file for faster processing. This column is included by default when you export translations from Altera.

Your translations import file is missing one or more required columns.

Required columns:

At least one of:

Could not resolve the resource ID from the ID, Identification, or Handle column. Make sure the ID column contains a valid Shopify numeric ID (like 8079393521850) or a GraphQL ID (like gid://shopify/Product/8079393521850). When importing across stores, include the Handle column so Altera can look up the resource by handle on the target store.

For metafield translations, this error also occurs when the metafield does not exist on the store. Altera resolves metafield translations by looking up the metafield by its namespace.key handle on the parent resource. If the metafield has not been created yet, the lookup fails and this error is returned. Make sure the metafield exists on the store before importing its translations - you can create it first with a regular metafield import or by setting its value in the Shopify admin.

The 'Type' column contains a resource type that is not recognized. Supported resource types include:

Rows with unknown types will be skipped.

A translation row was skipped because it's missing either the Locale or Field value. Both are required to register a translation.

Shopify refused to save a translation. The message names the field and the language of the translation that Shopify rejected. This can happen when:

When the message names one translation, this is a warning: Altera still imports the other translations for the same item. When Shopify rejects the whole item (for example, an invalid resource ID), the item fails.

Failed to delete some translations. The translations may have already been removed, or the resource may no longer exist.

When using the NEW command, the translation for this field and locale already exists. The existing translation was preserved (not overwritten). Use MERGE or UPDATE command if you want to overwrite existing translations.

Handle-based lookup is not supported for this resource type. The translation import can resolve resources by handle for common types like Products, Collections, Metaobjects, Pages, Articles, Blogs, and Menus. For other resource types (e.g., Online Store Theme, Email Template), you must provide a numeric ID or Identification value.

A nested resource type (such as a Metafield, Product Option, or Product Option Value) was specified with a handle but without valid parent information. Nested resources require a parent to be identified - for example, a metafield handle like custom.my_field needs a parent product handle to know which product's metafield to look up. Make sure the Parent Type and either Parent ID or Parent Handle columns are populated.

Your translations import file uses the Handle column for resource identification instead of ID/Identification. This is useful for importing translations across stores (where IDs differ), but is slower because each handle requires an API lookup. For faster imports on the same store, include the ID or Identification column.

The language specified in your translations import file is not enabled on the Shopify store. Before importing translations for a language, you must first add and enable that language in the Shopify admin.

To resolve this, go to Shopify Admin → Settings → Languages and add the language you are trying to import translations for. Once the language is enabled, retry the import.

The default (source language) content for this field in the import file does not match the content on the target store. This is expected when transferring translations between stores that have different source text. Altera automatically uses the target store's content digest so the translation is applied successfully.

No action is needed. This message is informational to let you know the source text differs. The translation will still be imported using the correct content digest from the target store.

The translated handle value is already in use by another resource on this store. Shopify requires that translated handles are unique across all resources of the same type.

To fix this, change the translated handle value in your import file to something unique. Note: if the translated handle is identical to the product's own default handle, Altera automatically skips it since no translation is needed.

The market name specified in the Market column (the market of the adaptation) does not match any market configured on the store.

To fix this, check the market name in your import file matches exactly (case-insensitive) with a market name in your Shopify admin under Settings > Markets. You can also use a market GID (e.g., gid://shopify/Market/12345) or a numeric market ID.

Shopify rejected the handle translation. This commonly happens when:

This is a warning - other translations in the same group are still imported successfully.

The resource has exceeded Shopify's limit on the number of translation keys. For themes, Shopify allows a maximum of 3,400 translation keys per locale.

This typically happens when importing translations for a theme that already has many translation keys. To fix this:

For more details, see Shopify's locale file requirements.

A translation value exceeds Shopify's 1,000 character limit per translation key. Shopify will reject any translation value longer than 1,000 characters.

To fix this, shorten the translated content to 1,000 characters or fewer. This limit applies to all translatable resources including themes, products, collections, and pages.

For more details, see Shopify's locale file requirements.

A Matrixify-format translations file uses an Entity value that Altera does not recognize. Supported entities are Product, Collection, Page, Blog, Blog Post, Metaobject, Menu, and Shop. The affected rows are skipped.

Altera could not resolve a translatable resource for a Matrixify row. The Entity ID was missing or did not exist on the target store, and the Entity Handle could not be matched to a resource either. The row is skipped.

A field like Option1 Name, Option1 Value, or Variant Metafield: was used on an Entity other than Product. These field translations are only valid for products. The row is skipped.

A Variant Metafield: row in a Matrixify file did not include a variant identifier in the Entity Handle column. Variant metafields require the product-handle.variant-title format so Altera can target the correct variant. The row is skipped.

An Option1 Value (or similar) row in a Matrixify file did not include the source option value in the Original Value column. Altera uses the original value to locate the option value being translated. The row is skipped.

A Matrixify-format translations file uses a Field label that Altera does not recognize. Supported labels include Title, Body HTML, Handle, Vendor, Type, SEO Title, SEO Description, Option<N> Name, Option<N> Value, Metafield: namespace.key, and Variant Metafield: namespace.key. The row is skipped.

A Matrixify-format translations file has been detected. Altera supports importing this format, but Altera's own format is faster (filters by locale, market, resource type, metafield, field, theme, and product/collection filters), supports market-scoped translations, and covers more translatable resource types (theme, email templates, collection filters, media alt text). Export translations from Altera once and use that format for subsequent imports.