At various places throughout the app you may encounter a warning or error code. These codes are formatted like ABC001. This document provides more context on the error codes as well as tips to resolve them.

These codes will appear when you upload a spreadsheet to be imported with the app.

There was an error opening the file you uploaded. Please try again and contact us if the problem persists.

You can upload a ZIP file with multiple CSV files to have them processed at once. However in this case the app did not detect any CSV files in the zip file you uploaded.

If you want to process multiple Excel sheets at the same time you can combine them into a single Excel workbook and upload that.

We couldn't determine if your file was CSV, Excel, or a valid ZIP. Please upload either a CSV file, an Excel workbook with the .xlsx extension, or a ZIP file containing CSV files so our system can process it.

Our system tried to read your file but did not detect any sheets with the required structure. Ensure your file includes sheets that match one of our supported object types (for example, a valid Products or Orders sheet) and try again.

Your spreadsheet contains columns that Altera does not recognize and these columns will be ignored when you import data through the app.

The most common cause of this is trying to import data that does not match the Altera/Matrixify format. To fix this, make sure your spreadsheet matches the format in our documentation ( Product Fields for example).

The file you uploaded appears to be a product export from Shopify's admin in Shopify's native format. Altera requires product files to be in the Altera/Matrixify format instead. See our Product Fields documentation for the correct format.

You can convert your file to the Altera format by going to the 'Transform data' section of app in the left menu. Note that even if you convert a Shopify product export to the Altera/Matrixify format, some data may not come through.

If you're trying to copy products from one Shopify store to another, the best approach is to:

This ensures all product data is captured and transferred correctly.

Some columns can appear multiple times in a spreadsheet but others cannot. Make sure that you don't have any columns with duplicate names besides Tags and Image Src.

The ID column should either be empty, contain a number like 8106245782738, or contain a GraphQL identifier like gid://shopify/Products/8106245782738. If it doesn't it may cause problems with the import. If your ID is a number, make sure it is a whole number, like 8106245782738, and not formatted as a decimal number like 8106245782738.0.

Excel has a character limit of 32,767 characters per cell. When metafields with exactly this character count are detected, they will be ignored during import to prevent data corruption in Shopify. This typically happens when Excel has truncated longer text values. For large metafield values, consider using CSV files for importing the values.

It looks like you are trying to upload an export of your WooCommerce products to Altera. Please try uploading the file again in the Altera/Matrixify format instead.

You are using the DELETE command in your import. Please note that deleting items is permanent and cannot be undone. The deletion will also process any hidden rows in your spreadsheet, so make sure to review your data carefully before proceeding.

You are using the REPLACE command in your import. When replacing items, the existing item will be completely deleted and recreated with the new data. This means all existing data not included in your import will be lost. The replacement will also process any hidden rows in your spreadsheet, so make sure to review your data carefully before proceeding.

ZIP files uploaded for import should not contain subdirectories. All CSV files should be placed at the root level of the ZIP file. Please restructure your ZIP file to place all CSV files in the root directory without any subdirectories.

The ZIP file you uploaded contains files that are not CSV files. ZIP files for import should only contain CSV files (plus any system files like .DS_Store which are automatically ignored). Please remove any non-CSV files from your ZIP file and try again.

The value provided cannot be converted to true/false. Boolean columns in your spreadsheet must contain recognized true or false values.

Accepted true values:

Accepted false values:

Values are case-insensitive, so TRUE, True, FALSE, and False are also valid. Make sure all values in boolean columns match one of these accepted formats.

The file you uploaded appears to be an order export from Shopify's admin in Shopify's native format. Altera requires order files to be in the Altera/Matrixify format instead, which contains more data than Shopify's native export.

You can convert the file in the 'Transform data' section of the app. Note that even if you convert a Shopify order export to the Altera/Matrixify format, not all order data will come through. Shopify's native order export is missing many fields that are required for a complete order import. For example:

If you're trying to copy orders from one Shopify store to another, the best approach is to:

This ensures all order data is captured and transferred correctly.

The system could not find a file analysis for the uploaded file. This typically occurs when trying to process a file that hasn't been analyzed yet. The file analysis should be triggered automatically when a file is uploaded.

If you continue to see this error, please contact support.

The file analysis completed successfully, but no analysis data was found. This is an unexpected error that indicates a problem with the analysis process.

Please try re-uploading your file. If the problem persists, contact support.

The system was unable to analyze your file due to an error. This could be caused by:

Try re-uploading your file. If the error persists, verify that your file is a valid CSV, Excel (.xlsx), or ZIP file. Contact support if you need further assistance.

The file analysis took too long to complete and timed out. This can happen with very large files or during periods of high system load.

Please try again in a few moments. If the problem persists with the same file, consider:

The Command column contains a value we don't recognize. Valid commands are:

Check your Command column for typos (e.g., "CREATE" instead of "NEW") and update them to one of the supported commands above. You can also leave the Command column blank to use the default MERGE behavior.

The file you uploaded appears to be an Etsy product listings export. This file needs to be converted to the Shopify format before importing.

Use the Etsy Products transformation in the Transform data section to convert this file. See How to Migrate Etsy Products to Shopify for step-by-step instructions.

The file you uploaded appears to be an Etsy Order CSV export. This format gives a summary of each order but does not include the individual line items, which are required for importing into Shopify.

To import your Etsy orders, you need to export the Order Item CSV from Etsy instead. See How to Migrate Etsy Orders to Shopify for step-by-step instructions.

The file you uploaded appears to be an Etsy Order Item CSV export. This file needs to be converted to the Shopify format before importing.

Use the Etsy Orders transformation in the Transform data section to convert this file. See How to Migrate Etsy Orders to Shopify for step-by-step instructions.

Your spreadsheet has an ID column where the first row is blank, but subsequent rows contain ID values. This pattern often indicates a data formatting problem in your spreadsheet.

Why this matters: If there are any valies in the ID column it will be used to group related rows together. For example, a product with multiple variants will have the product ID in the first row, and the variant rows below it share that same ID. When the importer sees a blank ID, it assumes those rows belong to the same item as the previous row.

Common causes:

How to fix:

The file you uploaded appears to be a Shopify theme ZIP file. Altera is designed for importing and exporting data like products, orders, and customers-not for managing themes.

How to upload themes to Shopify:

Theme ZIP files typically contain folders like assets, config, layout, locales, sections, and snippets, along with .liquid template files. If you intended to upload a data file (like products or orders), make sure you're uploading a CSV, Excel, or ZIP file containing CSV files instead.

The ID column in your spreadsheet contains values in scientific notation (e.g., 1.48E+13). This is typically caused by Excel automatically converting large numeric IDs into scientific notation format. This is a critical issue because the ID column is used to group rows together during import - when IDs are in scientific notation, many different rows can appear to have the same ID, causing them to be incorrectly grouped as a single record.

How to fix:

Tip: When working with large numeric IDs, always format the column as Text before pasting values to prevent Excel from converting them.

Your spreadsheet was matched to a Shopify data type, but all detected sheets contain errors that prevent the import from starting. Review the error messages shown for each sheet and correct the issues in your spreadsheet before re-uploading.

The CSV file could not be parsed because it contains formatting errors such as mismatched quotes, inconsistent column counts, or other structural issues. This typically happens when:

How to fix:

The easiest fix is to open the CSV file in Google Sheets or Excel and then save it as a new CSV file. This will automatically re-format the file with proper quoting and consistent columns.

If that doesn't work, you can manually inspect and fix the file:

Tip: If you originally exported the file from another application, try re-exporting it. Many applications have options for CSV export that handle quoting automatically.

Error codes related to data formatting and validation that can occur across different object types (orders, customers, products, etc.).

The phone number provided in your import is not in a valid format that Shopify accepts. Shopify is fairly strict about phone numbers and may reject numbers that are accepted in other platforms.

To ensure the phone number is accepted we recommend the following:

For US phone numbers specifically, Shopify rejects the area code 555 and all area codes starting with 1 as those are not real phone numbers.

Excel formatting tip: When entering phone numbers that start with a plus sign (like +16308545555), Excel may interpret them incorrectly or apply unwanted formatting. To prevent this, prefix the phone number with a single quote character (e.g., '+16308545555). The quote tells Excel to treat the value as text, and it won't be visible when the file is processed.

The province/state code provided in your import is not valid for the specified country. Shopify uses ISO 3166 standard province codes, and each country has its own set of valid province codes.

How to fix this:

Common examples:

If you're importing addresses for a country that doesn't require province codes, simply leave the province column empty rather than trying to provide a value.

The country code provided in your import is not valid. Shopify uses ISO 3166-1 alpha-2 standard country codes, which are two-letter codes that represent countries.

How to fix this:

Common examples:

Common mistakes:

The email address provided in your import is not in a valid format. Shopify validates email addresses to ensure they follow proper email formatting standards.

How to fix this:

Common examples of valid emails:

Common examples of invalid emails:

The value provided is not a valid number or cannot be converted to a number. This error occurs when numeric fields contain text, special characters, or formatting that cannot be interpreted as a valid numeric value.

This error applies to various numeric fields across different import types including:

How to fix this:

Common examples:

Invalid values:

Valid values:

The first name or last name provided in your import is not valid. Shopify has certain requirements for name fields that must be met for the import to succeed.

Common causes:

How to fix this:

Note: The support for emoji in name fields varies depending on what type of data you're importing. Some Shopify resources accept emoji in names while others do not. If you're seeing this error, the specific data type you're importing does not support emoji characters in the name field.

A required field in your import is empty or blank. Shopify requires certain fields to have a value and will reject records where these fields are missing.

Common required fields include:

How to fix:

Review the field mentioned in the error and provide a valid value. If you're updating existing records and don't want to change a field, you can leave it empty only if it's not required for the operation.

The value provided is too long and exceeds Shopify's maximum character limit for this field.

Common character limits:

How to fix:

Shorten the value to fit within the allowed character limit. If you're working with long text content, consider using a metafield with a larger capacity instead.

The value provided is too short and does not meet Shopify's minimum length requirement for this field.

How to fix:

Provide a longer value that meets the minimum length requirement. Check the specific field's requirements in Shopify's documentation.

The value you're trying to use is already taken by another record. Shopify requires certain fields to be unique across your store.

Fields that must be unique:

How to fix:

The ID or reference you provided does not match any existing record in your Shopify store. This typically happens when trying to link to another resource that doesn't exist.

Common causes:

How to fix:

The value provided is not valid for this field. This is a general validation error that occurs when the input doesn't meet Shopify's requirements.

Common causes:

How to fix:

Review the field's expected format in the documentation and ensure your value matches. Check for any special characters, encoding issues, or formatting problems.

You've reached a Shopify limit for this type of resource. Shopify imposes limits on various resources based on your plan.

Common limits:

How to fix:

The value provided doesn't match the expected format or constraints for this specific field type. This is common with metafields and fields that have specific validation rules.

Common causes:

How to fix:

The data type provided doesn't match what's expected for this field. This occurs when the wrong type of data is provided (e.g., text instead of a number).

Common causes:

How to fix:

These codes indicate that a row was skipped during import based on the command used and whether the item exists in Shopify. Skipped rows are not errors - they are expected behavior when using NEW, UPDATE, or DELETE commands with items that don't match the command's requirements.

You used the NEW command to create an item, but an item with the same identifier already exists in your Shopify store. The row was skipped to prevent creating duplicates.

Why this happens: The NEW command is designed to only create items that don't already exist. When it finds a matching item, it skips the row rather than failing.

How to resolve:

You used the UPDATE command to update an item, but no matching item was found in your Shopify store. The row was skipped because there's nothing to update.

Why this happens: The UPDATE command is designed to only update items that already exist. When it can't find a matching item, it skips the row rather than failing.

How to resolve:

You used the DELETE command to delete an item, but no matching item was found in your Shopify store. The row was skipped because there's nothing to delete.

Why this happens: The DELETE command is designed to only delete items that exist. When it can't find a matching item (perhaps because it was already deleted), it skips the row rather than failing.

How to resolve:

When importing a ZIP file containing multiple CSV files, the system could not find a CSV file matching the expected sheet name. This typically occurs when the ZIP file structure doesn't match what was detected during file analysis.

How to resolve:

The file format is not supported for this operation. Altera supports Excel (.xlsx), CSV, and ZIP files containing CSV files.

How to resolve:

Error and warning codes that occur when dealing with smart and manual collections

The collection that already exists in Shopify is a smart collection, but the import is trying to treat it as a manual collection. Shopify does not allow you to convert a smart collection to a manual collection. You can replace the collection however by setting the 'Command' column to REPLACE.

The collection that already exists in Shopify is a manual collection, but the import is trying to treat it as a smart collection. Shopify does not allow you to convert a manual collection to a smart collection. You can replace the collection however by setting the 'Command' column to REPLACE.

Shopify does not support more than 60 rules for a smart collection. Your import contains a collection with more than 60 rules, which exceeds Shopify's limit.

How to fix this:

Multiple collections were found with the same title, so the system cannot determine which one to update. Collection titles are not unique in Shopify, so when multiple collections share the same title, you need to use a more specific identifier.

How to fix this:

When creating a smart collection rule based on a metafield, the system could not find the corresponding metafield definition. Make sure that the metafield definition exists in your Shopify store, and has the 'Smart collection' enabled, before creating a smart collection rule that references it.

The metafield condition column format is invalid. When creating a smart collection rule based on a metafield, the column must follow the correct format:

For example: Metafield: custom.size or Variant Metafield: custom.color

Make sure your metafield condition includes the namespace and key separated by a period (.).

For more information about smart collection rule formats, see the Smart Collection Fields documentation.

The product specified in your import could not be found on the store. When linking products to a manual collection, the system first tries to find the product by ID, then falls back to the handle. If neither works, this warning is shown and the product is not added to the collection.

How to fix this:

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

The Shopify API rejected the discount data and refused to save it. This typically occurs when the discount configuration violates Shopify's business rules or contains invalid data that passed initial validation but failed at the API level.

The discount type specified in your import is not valid. The 'Type' column must be one of: 'Amount off Products', 'Amount off Order', 'Free Shipping', 'Buy X Get Y', or empty.

The discount method specified in your import is not valid. The 'Method' column must be either 'Code', 'Automatic', or empty.

The system attempted to create a discount with a type that is not supported by the discount creation API. This is an internal error that should be reported if encountered.

The date format provided for a discount field (such as start date or end date) is invalid. Expected format is YYYY-MM-DD HH:MM:SS or YYYY-MM-DD.

The usage limit value provided for the discount is not a valid number. Usage limits must be whole numbers (integers) indicating how many times the discount can be used.

The discount with the specified ID could not be found in your Shopify store. This may occur when trying to update or delete a discount that doesn't exist.

The system tried to delete a discount with a type that is not supported by the deletion API. This is an internal error that should be reported if encountered.

The system failed to add multiple codes to an existing discount. This typically happens when trying to add duplicate codes or codes that violate Shopify's validation rules.

The 'uses per order limit' value provided for the discount is not a valid number. This field must be a whole number (integer) indicating how many times the discount can be applied within a single order.

The customer segment specified in your discount cannot be found in your Shopify store. Make sure the segment name matches exactly and that the segment exists in your store.

The customer with the specified email address cannot be found in your Shopify store. Make sure the email address is correct and that the customer exists in your store.

The system could not determine the discount type from the provided data. This is an internal error that should be reported if encountered.

The system attempted to update a discount with a type that is not supported by the discount update API. This is an internal error that should be reported if encountered.

Importing discounts is still in beta. Please test with 1 or 2 discounts first to ensure everything works as expected before importing larger datasets.

The discount type was not specified in the import data. Make sure your import includes the discount type information or that existing discounts have their type properly identified.

The discount value must be a valid number. This error occurs when the 'Value' column contains text or other non-numeric values that cannot be converted to numbers. For percentage discounts, use a numeric value (e.g., 10.00 for 10% off). For fixed amount discounts, use the monetary value without currency symbols (e.g., 25.00 for $25 off). Ensure all values in the 'Value' column are either empty or contain only numeric values.

Numbers should use a period (not comma) for decimal separation and should not include thousands separators. For example, use 1234.66 instead of 1,234.66 or 1234,66.

When you specify a 'Minimum Value' for a discount, you must also set the 'Minimum Requirement' column to either 'Amount' or 'Quantity'. This tells Shopify whether the minimum requirement is based on:

Make sure that every row with a 'Minimum Value' also has a corresponding 'Minimum Requirement' set to one of these valid values. Empty or invalid values in the 'Minimum Requirement' column will cause the discount import to fail.

When you specify a 'Minimum Requirement' for a discount (either 'Amount' or 'Quantity'), you must also provide a corresponding value in the 'Minimum Value' column. This value determines the threshold that customers must meet to qualify for the discount.

For example:

Make sure that every row with a 'Minimum Requirement' set to 'Amount' or 'Quantity' also has a valid numeric value in the 'Minimum Value' column. Empty values will cause the discount import to fail.

This error occurs when trying to configure subscription-related discount fields on a store that doesn't have a subscription app installed. Shopify only allows subscription discount settings when the store has a subscription management app active.

The fields that require a subscription app are:

How to fix this:

If you don't need subscription functionality for your discounts, simply remove these columns from your spreadsheet and the import will proceed successfully.

Error and warning codes for importing and exporting files.

In some situations stores that are on a Shopify Trial are not able to upload files through the API. This is related to the store's subscription to Shopify, it has nothing to do with being on a paid or free plan with Altera. If your files fail to upload you will need to either switch to a paid Shopify plan or reach out to Shopify support for more help. In some situations this also applies to uploading images when you create new products.

Alt text is required when updating existing files. The UPDATE command requires you to provide the 'Alt' column with a value to update the file's alt text. If you want to replace the file entirely rather than just updating its metadata, use the REPLACE command instead.

The system failed to download and stage the media file for upload to Shopify. This error occurs when importing VIDEO or 3D model files (MODEL_3D) that need to be staged before uploading to Shopify's servers.

Media types are automatically detected from file extensions when not explicitly specified:

Common reasons for this error include:

How to fix this:

Note: IMAGE and EXTERNAL_VIDEO media types do not require staging and are uploaded directly.

Codes related to creating and managing import or export jobs.

In order to provide a reliable service to all users you may have a limit to the number of jobs you can run at the same time. You can either cancel another job or wait for it to finish before starting a new job.

You have reached the maximum number of scheduled jobs allowed by your plan. To create a new scheduled job, you'll need to either disable an existing scheduled job or upgrade your plan for a higher scheduled job limit.

Your export has reached the maximum number of rows allowed by your current plan. The export was completed up to this limit, but additional data could not be included in the file.

To export more data, you can:

The exported file will contain a message indicating where the row limit was reached.

The single CSV export format only supports exporting one object type at a time. To export multiple object types, use the ZIP format (matrixify_zip) instead, which creates separate CSV files for each object type in a single archive.

You cannot enable scheduling for a job that does not have a schedule configured. Please configure the schedule settings (start time and repeat interval) before enabling scheduling.

An error occurred while applying data transformations to your export. The export completed using the original data without the transformations applied.

To resolve this:

If the problem persists, please contact support with your job ID for assistance.

Error and warning codes for importing and exporting menus.

When you import menus you need to have menu item columns like "Menu Item: Resource Type" and "Menu Item: Title". To get these columns in an export, make sure that you select the 'General' and 'Menu items' groups when configuring which fields to export.

The Shopify API rejected the menu data and refused to save it. This typically occurs when the menu configuration violates Shopify's business rules or contains invalid data that passed initial validation but failed at the API level.

The 'Menu Item: Title' column contains empty values. When importing menus, every menu item must have a title. Check your spreadsheet and ensure that all rows with menu items have a title specified in the 'Menu Item: Title' column. Empty titles will prevent the menu items from being created properly in Shopify.

The menu title is required when creating a new menu. Make sure your import includes the 'Title' column with a valid menu name for each menu you want to create. Empty or missing titles will prevent the menu from being created in Shopify.

A circular reference has been detected in your menu structure. This occurs when a menu item is configured to be its own parent or ancestor, creating an infinite loop in the menu hierarchy.

Common scenarios that cause this error:

How to fix this:

Example of problematic data:

To resolve this, ensure your menu hierarchy flows in one direction without any item becoming its own ancestor.

A menu item has the same value for both 'Menu Item: ID' and 'Menu Item: Parent ID', which creates a direct self-reference. A menu item cannot be its own parent in the menu hierarchy.

This is a specific case of a circular reference where a menu item directly references itself as its parent, rather than indirectly through other menu items.

How to fix this:

Example of problematic data:

Corrected data:

or

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.

Required columns are missing from your metafield definition import. For metafield definitions to import correctly, your spreadsheet must include 'Type: Name', 'Namespace', and 'Owner Type' columns. Additionally, the 'Type: Name' value is required on every row when creating new metafield definitions. These fields are necessary for Shopify to properly create the metafield definitions.

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

One or more rows are missing 'Type: Name' values. The metafield type (e.g. single_line_text_field, number_integer) is required when creating new metafield definitions. Existing definitions being updated do not need this value since the type cannot be changed after creation.

One or more rows are missing 'Owner Type' values. The owner type (e.g. PRODUCT, ORDER, CUSTOMER) is required to look up existing metafield definitions and to create new ones. Without it, Altera cannot determine which Shopify object the metafield definition belongs to.

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:

To resolve this issue, remove the protected metafields from your import file. These metafields must be managed directly through Shopify's admin or the app that owns them.

The metafield value is exactly 32,767 characters long, which is the maximum cell length in Excel. This strongly suggests the value was truncated by Excel when the file was saved, so Altera skips the update to avoid corrupting the data.

To resolve this issue, use a CSV editor or text editor that does not have a cell character limit (such as Google Sheets or LibreOffice Calc) to edit the file and ensure the full value is preserved.

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.

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

The metaobject definition type is required for metaobject imports and cannot be empty. This column specifies which metaobject definition the imported data should use. Make sure your import file includes the 'Definition: Type' column with valid metaobject definition types for all rows containing metaobject data.

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.

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

The Shopify API rejected the catalog data and refused to save it during an update operation. This typically occurs when the catalog configuration violates Shopify's business rules or contains invalid data that passed initial validation but failed at the API level.

The market specified in your catalog import cannot be found in your Shopify store. Make sure the market handle matches exactly and that the market exists in your store. Check that the market is properly configured and active.

The company location specified in your catalog import cannot be found in your Shopify store. Make sure the company location name matches exactly and that the location exists in your store. Verify that the company location is properly set up in your B2B configuration.

The system failed to create a price list for the catalog. This typically happens when there are issues with the price list configuration or when Shopify's API rejects the price list data. Check your price list settings including currency, name, and any parent adjustment configurations.

You cannot change the publication ID of an existing catalog during an update operation. The publication ID is set when the catalog is created and cannot be modified afterward. If you need to change the publication association, you may need to replace the catalog entirely using the REPLACE command.

The Shopify API rejected the catalog data and refused to create the catalog. This typically occurs when the catalog configuration violates Shopify's business rules or contains invalid data that passed initial validation but failed at the API level during creation.

After creating a catalog, the system could not find the associated price list that should have been created. This is an internal error that indicates an issue with the catalog creation process. Please try again or contact support if the problem persists.

The 'Type' and 'Type Values' fields are required when creating a catalog. These fields determine the context of the catalog (such as which markets or company locations it applies to). Make sure your import includes both the catalog type (e.g., "Market" or "Company Location") and the corresponding values (e.g., market handles or location names).

Catalogs for sales channels/apps cannot be created through the API. Only catalogs for markets and company locations are supported. If you need to create catalogs for apps or sales channels, you'll need to do this manually through the Shopify admin interface.

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

You are trying to set a specific Store Credit Amount with an expiration date, but the customer already has a non-zero store credit balance.

When using the 'Store Credit: Amount' column, the system creates a transaction for the difference between the current balance and the target amount. If you provide an expiration date, it would only apply to this adjustment transaction, not the entire balance. This would result in different parts of the balance having different expiration dates, which is not the intended behavior when setting a total amount.

To resolve this, you can:

The date format provided for the store credit balance expiry date is invalid. The 'Store Credit: Expires At' column contains a value that cannot be parsed as a valid date/time.

The date should be in a standard format that can be recognized, such as:

Make sure all values in the 'Store Credit: Expires At' column are either empty or contain properly formatted date/time values.

The expiry date provided for the store credit balance is not in the future. The 'Store Credit: Expires At' column contains a date/time that is in the past or is the current date/time.

Store credit expiry dates must be set to a future date to be valid. Check that the date you're providing is after the current date and time.

How to fix this:

Store credit columns detected in your customer import. These operations affect real money and customer account balances. Please double-check your data carefully before importing, as incorrect values could result in financial discrepancies or customer billing issues.

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

Your import file contains an "Is Default" column with a value set to true. The default store location cannot be changed through the Shopify API - this is a limitation of Shopify's system.

How to set the default location:

The rest of your location data will still be imported. Only the default location setting will be skipped.

Your import file has a Country column with values but no Country Code column. Location imports require the two-letter ISO country code (e.g., "US", "CA", "GB") rather than the full country name.

How to fix this:

You can find the full list of country codes at ISO 3166-1 alpha-2.

The Country column (with full names) is optional and used for display purposes only. The Country Code column is required for the import to work correctly.

Locations managed by a fulfillment service cannot be edited through the Shopify API. These locations are created and controlled by third-party fulfillment providers (e.g., ShipBob, Deliverr, Amazon FBA).

How to fix this:

Your import file references a location by name, but multiple locations exist with that name. This can happen when a location is deactivated and a new location with the same name is created (Shopify only enforces unique names among active locations).

How to fix this:

Shopify's API returned the error "Location could not be added, try again later." This is a temporary issue on Shopify's side. Altera will automatically retry up to 3 times with a 5-second delay between attempts before showing this error.

How to fix this:

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

The Shopify API rejected the company data and refused to save it during an update operation. This typically occurs when the company configuration violates Shopify's business rules or contains invalid data that passed initial validation but failed at the API level.

A company name is required when creating a new company. This error occurs when attempting to create a new company record without providing a value in the 'Name' column. The company name is a mandatory field in Shopify and must be specified for all new company records.

How to fix this:

The 'Location: Tax Exemptions' column contains invalid tax exemption values. This column must either be blank or contain a comma-separated list of valid tax exemption codes that Shopify recognizes.

Valid tax exemption codes include exemptions for specific regions and purposes, such as:

For a complete list of all valid tax exemption values, see the Shopify TaxExemption enum documentation.

How to fix this:

Example of valid data:

When updating a company, if you try to identify a location by name and multiple locations exist with the same name, this error occurs. Location names are not unique in Shopify's B2B system, so when multiple locations share the same name, the system cannot determine which one to update.

How to fix this:

Example:

Instead of:

Use:

This error occurs when using the UPDATE command for a company location that doesn't exist. The UPDATE command requires the location to already exist in the company before it can be updated.

How to fix this:

Example of valid data:

This warning occurs when trying to assign a customer as a contact to a company, but the customer is already associated with a different company. Shopify does not allow a customer to be a contact for multiple companies simultaneously.

This is a warning rather than an error - the company import will still succeed, but this specific customer will not be linked as a contact.

How to fix this:

This error occurs when trying to assign a catalog to a company location, but the catalog is configured to be assigned to Markets instead of Company Locations. In Shopify, catalogs can only be assigned to one type of context - either Markets or Company Locations - but not both.

How to fix this:

Note: Changing a catalog's context type will remove any existing Market assignments for that catalog. If you need the catalog assigned to both Markets and Company Locations, you'll need to create separate catalogs for each use case.

Your import file contains company location columns (such as 'Location: Phone', 'Location: Tax Setting', 'Location: Address 1', etc.) but is missing a location identifier column ('Location: ID' or 'Location: Name') with values.

When updating or creating company locations, each location must be uniquely identified so the system knows which location to update. Without an identifier, the system cannot determine which location the data belongs to.

How to fix this:

If you're creating new locations, the 'Location: Name' column is sufficient. If you're updating existing locations, using 'Location: ID' is recommended as it's the most reliable identifier (location names can be duplicated).

Example of correct data:

Or with Location IDs:

A customer specified as a contact or main contact for a company could not be found in your Shopify store. The customer must already exist in Shopify before they can be assigned as a company contact.

This is a warning rather than an error - the company import will still succeed, but the contact will not be linked.

How to fix this:

Common causes:

Example columns that can trigger this warning:

A catalog specified for a company location could not be found in your Shopify store. The catalog must already exist before it can be assigned to a company location.

This is a warning rather than an error - the company import will still succeed, but the catalog will not be assigned to the location.

How to fix this:

Common causes:

These codes are related to uploading blog posts (articles) and blogs.

The image for a blog post needs to be a complete URL that starts with http:// or https://.

Shopify needs to associate all blog posts with a blog on your store. If you are unsure of what to set this to, just add the 'Blog: Handle' column to your spreadsheet with the values 'blog' in each row.

Shopify blog posts only support one featured image, but you can include additional images in the body HTML of your post. This warning is raised if there's commas or pipe characters in the Image Src column because those are often used to separate different URLs.

Shopify does not accept blog post dates before January 1, 1970 (the Unix epoch). If you have blog posts with dates before this, you'll need to update them to a valid date range. This limitation is due to how Shopify handles date storage internally.

The published date is more than 10 years in the future, which might indicate a data entry error. While Shopify may accept future dates, having dates too far in the future could cause unexpected behavior or indicate that the year was entered incorrectly (e.g., typing 2224 instead of 2024).

The 'Published At' column contains a value that cannot be parsed as a valid date/time. The date should be in a standard format that can be recognized, such as:

Make sure all values in the 'Published At' column are either empty (for drafts) or contain properly formatted date/time values.

A 'Body HTML' value is exactly 32,676 characters long, which indicates that Excel has truncated the content. Excel has a cell character limit of 32,767 characters, and when content exceeds this limit, it gets cut off.

To avoid data loss, export your original data in CSV format instead of Excel. CSV files do not have the same character limitations as Excel cells, so your full Body HTML content will be preserved.

Multiple blogs were found with the same title, so the system cannot determine which one to update. Blog titles are not unique in Shopify, so when multiple blogs share the same title, you need to use a more specific identifier.

How to fix this:

These codes occur when trying to figure out which kind of Shopify object you are importing or exporting (e.g., products, orders etc..)

When trying to export objects, the provided object type wasn't recognized. Ensure you're using a valid object type (e.g., products or orders).

Sheet analysis didn't find a matching type for the label. Double-check your sheet configurations or labels before importing.

You tried to import using an object slug that isn't supported. Confirm it's a valid import type (e.g., products, customers).

A metafield reference value didn't start with gid://shopify/, so it couldn't be processed. Check that all reference handles match the expected gid://shopify/ format.

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

We're still working on importing draft orders. Please email us if you need more information about when this feature will be available or if you have specific requirements for draft order imports.

The draft order 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 name) provided in your import is incorrect.

The Shopify API rejected the draft order data and refused to save it during a creation operation. This typically occurs when the draft order configuration violates Shopify's business rules or contains invalid data that passed initial validation but failed at the API level.

You are trying to update a draft order that has already been completed (converted to a real order). Completed draft orders are locked and only their tags can be modified. Other changes require creating a new draft order.

The Shopify API rejected the draft order data and refused to update it. This typically occurs when the updated draft order configuration violates Shopify's business rules or contains invalid data that passed initial validation but failed at the API level.

The email address provided for the draft order is not in a valid format. Email addresses must follow the standard email format (e.g., [email protected]). Please check the email field and ensure it contains a properly formatted email address.

The date format provided for the 'Reserve Inventory Until' field is invalid. Expected format is YYYY-MM-DD HH:MM:SS or YYYY-MM-DD. Please ensure your date values match one of these formats.

Error and warning codes that occur when dealing with orders

Order sheets work best with either a Name or ID column for grouping. When neither column is present, the system will fall back to using "Top Row" column markers for grouping, or group all rows into a single order if no Top Row column exists.

Required columns, such as the Line: Type column are missing from the source file.

The Line: Type column must be one of these values:

Importing orders will trigger Shopify Admin staff notifications for each order unless they are disabled. Shopify does not provide a way for apps to detect if notifications are already turned off.

To disable order notifications, open up the Shopify admin and go to Settings > Notifications > Staff notifications and turn them off before importing large batches of orders.

Additionally, importing orders may trigger other applications that are configured to process new orders on Shopify. We recommend testing with 1-2 orders before importing large batches of orders.

Editing existing orders is not currently supported through the application. You may need to delete the existing order and create a new one with your desired changes.

This error occurs when processing a refund with insufficient line item data. When processing refunds, make sure to include all required line item information to properly associate the refund with the correct items.

Shopify limits new orders to 5 per minute on trial and development stores. If your store is on a trial or development plan, order imports will run more slowly due to this limitation. To increase the import speed, consider upgrading to a paid Shopify plan.

The date/time columns in your order import ('Processed At', 'Transaction: Processed At', 'Fulfillment: Processed At') must contain valid date/time values or be left blank. This error occurs when these columns contain text or other values that cannot be parsed as valid dates. Use standard date formats like 2024-01-15, 2024-01-15 14:30:00, or Jan 15, 2024 2:30 PM. Ensure all values in these columns are either empty or contain properly formatted date/time values.

When importing orders with fixed date payment terms, the 'Payment Terms: Due At' column must be provided and cannot be empty. This error occurs when you have specified a payment terms template that requires a fixed due date, but the corresponding 'Payment Terms: Due At' column is missing or empty. Ensure that for fixed date payment terms, you include the 'Payment Terms: Due At' column with a valid date/time value specifying when the payment is due.

More than one existing order matches the criteria provided in your import (ID or Name). Each row in your import must uniquely identify a single order. Check that your Order ID or Name values are unique and don't match multiple existing orders in your store.

You can only update a single fulfillment per order when the Fulfillment ID is not specified. If you need to update multiple fulfillments for the same order, you must provide the specific Fulfillment ID for each fulfillment you want to update.

When importing orders, if you provide any shipping or billing address information, you must provide all required address fields. This error occurs when some address fields are filled but others are missing.

Required shipping address fields:

Required billing address fields:

How to fix this:

Shopify does not allow editing orders that were placed in a currency different from your store's base currency. You can only add line items to orders that were placed in your store currency.

To resolve this:

Note: Shopify doesn't allow adding Line Items to an Archived Order – the app will automatically unarchive the order, add the line items, and then re-archive it if it was originally archived.

When using the Line: Command column with the MERGE value to add line items to an order, you must include at least one line item row in your spreadsheet.

To resolve this:

The fulfillment request contains an invalid line item quantity. This typically happens when:

How to fix this:

Error and warning codes that occur when dealing with product data

Products with multiple variants need to have the Option1 Value column set to identify the different variants.

The product status field must be empty or one of the following: ACTIVE, ARCHIVED or DRAFT.

The spreadsheet it identifying products by title but more than one product with that title exists in Shopify. A product title needs to be unique when using it to update a product. If you have multiple products with the same title you can either use the ID or Handle column to identify the product you want to update.

The Variant Weight column should just contain a number. If you want to set the unit of the weight you can set that separately in the Variant Weight Unit column.

When importing reference metafields the values need to be in the GID format like gid://shopify/Metaobject/123456789 or ["gid://shopify/Metaobject/123456789"] if it's a list of references. We are working on adding support for looking up references by handle. Please contact us if you feel this feature should be prioritized.

When including an 'Option1 Name' column in your product import, you must also include the corresponding 'Option1 Value' column. Option names define the type of variant (like "Size" or "Color"), while option values define the specific variants (like "Small" or "Red").

For each product with an 'Option1 Name' defined, you must provide a corresponding value in the 'Option1 Value' column. Empty option values will cause errors when creating variants in Shopify. Ensure all products with option names have corresponding option values set.

When updating variant data, you must include at least one column that identifies which variant to update, such as 'Variant ID', 'Variant SKU', or 'Variant Barcode' if the product has more than one variant. Without an identification column, the system cannot determine which variant should receive the updates. Add one of these columns to your import file to resolve this issue.

The product's title is required in each row of your import file. This is necessary for the system to properly group variants belonging to the same product. Make sure every row in your import file has a product title, even when importing multiple variants of the same product.

The price columns ('Variant Price', 'Variant Compare At Price', 'Variant Cost') should contain only plain numbers with a period (not comma) for decimal separation and no currency symbols. For example, use 19.99 instead of $19.99 or 19,99. This ensures that prices are correctly interpreted by Shopify when imported.

The meta description field (Metafield: description_tag [single_line_text_field]) should not contain newline characters. Newlines in meta descriptions can cause issues with SEO and may not display correctly in search engine results. Altera will attempt to remove any newline characters from this field during import, but it's best to ensure your source data does not include them.

The meta description field (Metafield: description_tag [single_line_text_field]) should not contain HTML elements. HTML in meta descriptions is typically stripped by search engines and may cause unexpected display issues in search results. Using plain text in meta descriptions is recommended for better SEO outcomes and proper display across all platforms. Please remove HTML elements like <div> or <p> tags from your meta descriptions.

When setting a compare-at price for a specific market, you must also set the regular price for that same market. Shopify requires that any market with a compare-at price must also have a regular price defined. Update your spreadsheet to include the regular price for any markets where you've specified a compare-at price.

The meta description field (Metafield: description_tag [single_line_text_field]) exceeds Shopify's recommended maximum length of 160 characters. While longer descriptions will be imported, search engines typically truncate meta descriptions to around 155-160 characters. For optimal SEO performance, keep your meta descriptions concise and within the recommended length to ensure they display properly in search results.

The meta title field (Metafield: title_tag [single_line_text_field]) exceeds Shopify's recommended maximum length of 70 characters. While longer titles will be imported, search engines typically display only the first 50-60 characters of meta titles in search results. For optimal SEO performance, keep your meta titles concise and within the recommended length to ensure they display properly in search results.

A title is required to create a new product. This error occurs when trying to create a product without providing a title field. This may also happen when trying to update products by SKU where the SKU doesn't exist on the store. In such cases, the system tries to create a new product but fails because there's no title provided in the import data.

If you are creating new products, ensure that each product row in your import file includes a 'Title' column with the product's name. If you are updating existing products by SKU you can ignore this error if you know that not all SKUs in your import file exist on the store.

The unit price data in the 'Variant Unit Price' column is not in the correct JSON format. This column requires a valid JSON object with the following structure:

Valid units: CL, CM, FLOZ, FT, FT2, G, GAL, IN, ITEM, KG, L, LB, M, M2, M3, MG, ML, MM, OZ, PT, QT, YD

Value requirements:

Tip: If you find JSON formatting difficult, consider using the separate unit price columns instead (Unit Price Total Measure, Unit Price Total Measure Unit, Unit Price Base Measure, Unit Price Base Measure Unit). See error code PRD031 for more information about these columns.

Special behaviors:

The 'Image Command' column contains an invalid value. This column specifies how images should be handled when importing products and must contain either 'MERGE', 'REPLACE', 'NEW', 'DELETE', or 'IGNORE' (case insensitive).

Make sure all values in the 'Image Command' column are either empty or one of the valid commands. Any other values will cause the import to fail.

The column contains values in Excel's scientific notation format (like 8.0335E+12 or 1.23E-05). This typically happens when:

How to fix this:

Prevention: Always format SKU and Barcode columns as "Text" in Excel before entering data, especially for UPC codes, EAN codes, or other long numeric identifiers that should be treated as text rather than numbers.

You are trying to set inventory levels for a product variant at a location where the inventory item is not stocked. Before you can update inventory quantities, the product variant must first be stocked at that location.

If you are trying to set inventory using the Variant Inventory Qty column, the app will try to stock the variant at the oldest active location on your store. (It is not possible to see the default location for a store through the API.) If you want to stock the variant at a specific location, you can use the Inventory Available: [Location Name] column to set the inventory quantity.

You are trying to set inventory quantities for a product variant that has inventory tracking disabled. In Shopify, you cannot set inventory levels for variants that are not being tracked.

There are several ways to fix this:

The Harmonized System (HS) code provided is invalid. HS codes are used to classify goods for customs purposes.

If you are seeing this error, check that your HS codes:

You can search for valid HS codes on the UK's Integrated Online Tariff website.

Your import file has a 'Variant SKU' column but no product identification columns (ID, Title, Handle, or Variant ID). When importing by SKU alone, Altera must look up each SKU individually to find the matching product, which can be slow for large imports.

How to speed up your import:

Rename your 'Variant SKU' column to 'Variant SKU [ID]'. This tells Altera to use SKU as the primary identifier and enables a bulk lookup optimization that can significantly speed up imports.

Example:

Before:

After:

This optimization is most noticeable when importing hundreds or thousands of products by SKU.

Your import file has a 'Variant ID' column but no product identification columns (ID, Title, or Handle). When importing by Variant ID alone, Altera must look up each variant individually to find the matching product, which can be slow for large imports.

How to speed up your import:

Rename your 'Variant ID' column to 'Variant ID [ID]'. This tells Altera to use Variant ID as the primary identifier and enables a bulk lookup optimization that can significantly speed up imports.

Example:

Before:

After:

This optimization is most noticeable when importing hundreds or thousands of products by Variant ID.

Your import file has a 'Variant Barcode' column but no product identification columns (ID, Title, Handle, Variant ID, or Variant SKU). When importing by barcode alone, Altera must look up each barcode individually to find the matching product, which can be slow for large imports.

How to speed up your import:

Rename your 'Variant Barcode' column to 'Variant Barcode [ID]'. This tells Altera to use barcode as the primary identifier and enables a bulk lookup optimization that can significantly speed up imports.

Example:

Before:

After:

This optimization is most noticeable when importing hundreds or thousands of products by barcode.

Your store has multiple inventory locations, so the 'Variant Inventory Qty' column cannot be used when updating existing products. This column sets inventory at a single location and could overwrite inventory data at your other locations.

When creating new products, 'Variant Inventory Qty' is still allowed and will set inventory at your store's default location.

How to fix:

Use location-specific inventory columns instead. Replace 'Variant Inventory Qty' with 'Inventory Available: [Location Name]' where [Location Name] matches one of your store's locations.

Example:

If your default location is named "Main Warehouse":

Before:

After:

You can set inventory for multiple locations by adding additional columns:

Your store has multiple inventory locations, so the 'Variant Inventory Adjust' column cannot be used. This column adjusts inventory at a single location and could cause incorrect inventory counts at your other locations.

How to fix:

Use location-specific inventory adjustment columns instead. Replace 'Variant Inventory Adjust' with 'Inventory Available Adjust: [Location Name]' where [Location Name] matches one of your store's locations.

Example:

If your default location is named "Main Warehouse":

Before:

After:

You can adjust inventory for multiple locations by adding additional columns:

One or more of the unit price columns contains an invalid value. The unit price columns are:

Valid units: CL, CM, FLOZ, FT, FT2, G, GAL, IN, ITEM, KG, L, LB, M, M2, M3, MG, ML, MM, OZ, PT, QT, YD

Value requirements:

Special behaviors:

Example of correct usage:

This example means "500 grams per 1 kilogram" for unit pricing display.

Gift card products cannot be imported until gift cards have been enabled on your Shopify store. New stores do not have gift cards enabled by default.

To enable gift cards:

You don't need to actually create a gift card product - simply clicking the button will enable gift cards for your store. After this, you can import gift card products through Altera.

Your file contains a product metafield column (e.g., Metafield: custom.myfield), but no metafield definition exists for products with that namespace and key. However, a metafield definition with that namespace and key does exist for variants.

This usually means you intended to set a variant metafield instead of a product metafield.

To fix this:

Change your column header from:

To:

For example, if your column is Metafield: custom.color, change it to Variant Metafield: custom.color.

Your file contains a variant metafield column (e.g., Variant Metafield: custom.myfield), but no metafield definition exists for variants with that namespace and key. However, a metafield definition with that namespace and key does exist for products.

This usually means you intended to set a product metafield instead of a variant metafield.

To fix this:

Change your column header from:

To:

For example, if your column is Variant Metafield: custom.material, change it to Metafield: custom.material.

The location name in the Inventory Available: [Location Name] column header could not be matched to any location in your Shopify store. Inventory was not updated for this location.

This can happen if:

To fix this: Check the location name in your column header and make sure it matches the exact name of the location in your Shopify admin under Settings > Locations.

Error codes that appear when downloading files from remote sources (HTTP, FTP, Google Drive, etc.) and managing remote connections

The URL scheme is not supported. Currently supported schemes are HTTP, HTTPS, and FTP.

The URL format is invalid for the specified source type. Make sure you've entered a valid URL.

The file was not found at the specified URL. Please check that the URL is correct and the file exists.

Authentication is required or you have insufficient permissions to access the file. Check if the file requires login or specific permissions.

An HTTP error occurred when trying to download the file. This could be due to server problems or invalid requests.

The downloaded file is empty (zero bytes). Please check the source file.

Failed to connect to the server. Check your internet connection and verify the URL is correct.

The connection timed out while trying to download the file. This could be due to a slow connection or server issues.

The file download failed due to a general request error. Check the detailed error message for more information.

An unexpected error occurred during the HTTP download. Check the logs for more details.

Failed to connect to the FTP server. Check that the server address is correct and the server is running.

Authentication failed for the FTP server. Verify your username and password.

Unable to access the file on the FTP server. The file may not exist or you might not have permission to access it.

An error occurred during the FTP file transfer. Check your connection and try again.

The downloaded FTP file is empty (zero bytes). Please check the source file.

A general FTP error occurred. Check the detailed error message for more information.

An unexpected error occurred during the FTP download. Check the logs for more details.

The remote connection you are trying to use cannot be found. This may be because it was deleted or because the identifier provided is incorrect. Please verify that the remote connection exists and that you have access to it.

No hostname was provided for the FTP server connection. When configuring an FTP connection, the hostname (server address) is required. Please check your remote connection settings and ensure that the 'Host' field is filled in with a valid FTP server address.

The local file specified for upload cannot be found on the system. This typically occurs when trying to upload a file to an FTP server, but the source file path is incorrect or the file has been deleted or moved. Please verify that the file exists at the specified location before attempting to upload it.

Unable to upload the file to the FTP server due to permission issues. This error occurs when you lack write permissions to the target directory on the FTP server. Verify that:

Contact your FTP server administrator if you need additional permissions for the upload location.

An error occurred during the FTP file upload process. This could be due to various reasons such as:

Check the detailed error message for more information about what went wrong during the upload process.

An unexpected error occurred during the FTP upload process. This is a general error code for unexpected issues that occur when uploading files to an FTP server. Check the logs for more details about the specific error that occurred.

Failed to create a required subdirectory on the FTP server during file upload. This error occurs when:

Common causes:

How to fix this:

An unexpected error occurred during the remote file upload process. This is a general error code for unexpected issues that occur when uploading files to any remote connection type (HTTP, FTP, SFTP, etc.). Check the error message and logs for more details about the specific error that occurred.

An unexpected error occurred during the remote file download process. This is a general error code for unexpected issues that occur when downloading files from any remote connection type (HTTP, FTP, SFTP, etc.). Check the error message and logs for more details about the specific error that occurred.

The upload transfer is missing the local file path in its metadata. This typically occurs when attempting to upload a file to a remote server, but the system cannot find the path to the local file that should be uploaded. Check that the transfer was configured correctly with the required metadata including the local file path.

The upload transfer is missing the remote destination path. This error occurs when attempting to upload a file to a remote server (FTP, SFTP, etc.), but the system doesn't know where on the remote server to place the file. The remote file path specifies the destination location and filename on the remote server.

How to fix this:

No files were found matching the specified wildcard pattern on the FTP server. This error occurs when attempting to download a file using a wildcard pattern (e.g., export_*.csv), but no files on the server match the pattern.

How to fix this:

Failed to connect to the SFTP server. Check that the server address is correct and the server is running.

Authentication failed for the SFTP server. Verify your username, password or key file.

Unable to access the file on the SFTP server. The file may not exist or you might not have permission to access it.

An error occurred during the SFTP file transfer. Check your connection and try again.

The downloaded SFTP file is empty (zero bytes). Please check the source file.

The downloaded file is in a format that is not supported for importing. Please check our documentation for supported file formats.

The remote file exceeds the maximum allowed file size. Please try with a smaller file or contact support for assistance.

Rate limit exceeded when accessing the remote file. Please try again later or with a different source.

You have reached your plan's limit for the number of remote connections you can create.

How to fix this:

You cannot delete this remote connection because it is being used by one or more active repeating jobs. Before deleting the connection, you must first either:

To find which jobs are using this connection, go to the Jobs page and look for scheduled jobs that reference this connection.

An unhandled error occurred during the remote file download process. This is a general error code for unexpected issues.

These codes occur when the app is writing your output to a spreadsheet

You attempted to export using a data type the system doesn't recognize. Please try to reconfigure the job and run it again.

The export format is not recognized. Currently Altera only supports CSV and Excel files in the Altera/Matrixify format.

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 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.

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.

The Shopify API refused to save the translations. This can happen due to:

Check the error message for more details.

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.

These codes occur when interacting with the Shopify API.

Your import or export failed because the Shopify store is currently closed or paused, and API requests cannot be made to the store. This can happen when:

To resolve this, the store owner needs to reactivate their Shopify subscription or unpause their store in the Shopify admin.

The Shopify store has uninstalled the Altera app, so API requests can no longer be made on behalf of this store.

If you believe this is an error, you can reinstall the app from the Shopify App Store.

Your import or export failed because the Shopify store is not available and API requests cannot be made to the store. This can occur when:

Shopify imposes a daily limit on the number of product variants that can be created through the API. This error occurs when you've reached that limit for the current day.

When you encounter this error:

This is a Shopify platform limitation and cannot be bypassed through the application.

An error was returned from the Shopify API that was not related to internal server issues or product modification conflicts. This could be due to various reasons such as invalid data, API limitations, or other Shopify-specific constraints. The exact error message from Shopify will be provided with this code to help diagnose the specific issue.

Altera allows you to run multiple jobs at the same time and has a built-in retry mechanism when Shopify's API rate limits are reached. However, if many intensive API jobs are running simultaneously, the retries may exceed the maximum allowed attempts, causing the job to fail.

To resolve this:

If you continue to experience this issue, please contact us. We can adjust the API call allocation per job on our end to help prevent this from happening.

This error occurs when waiting for files to reach a terminal status (READY or FAILED) but the operation times out before all files complete processing. This can happen when:

If you encounter this error, you can try:

These codes appear when Shopify rejects an operation due to validation issues or business rule violations.

This error occurs when Shopify rejects the data you're trying to submit because it doesn't meet their requirements. Unlike technical API errors, these are usually related to the actual content of your data.

Common reasons for this error include:

The error message accompanying this code will provide specific details about what went wrong, which should help you correct your data before trying again.

Error codes related to API key permissions and access control.

This error occurs when the API key being used does not have the necessary permissions to perform the requested operation. Each API key can be configured with specific permissions that control which types of jobs (imports or exports) and which object types (products, orders, customers, etc.) it can access.

Common reasons for this error include:

How to fix this: