Error and Warning Codes
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.
You 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 Atlera/Matrixify format. To fix this, make sure your spreadsheet matches the format in our documentation ( Product Fields for example).
It looks like you are trying to upload an export of your Shopify products to Altera. Please try uploading the file again in the Altera/Matrixify format .
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.
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 it 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 it 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.
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.
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.
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.
Error and warning codes for importing and exporting metafield definitions.
The Shopify API did not return a newly-created metafield definition, possibly because a matching one already exists on the store.
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.
Please make sure that the spreadsheet you are importing include a 'Namespace' column.
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.
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 orders
All order sheets need to have either a Name or ID column to be able to group orders that span multiple rows
Required columns, such as the Line: Type or Line: ID column are missing from the source file.
The Line: Type column must be one of these values:
- Line Item
- Discount
- Shipping Line
- Transaction
- Refund Line
- Refund Shipping
- Fulfillment Line
- Ignore
Importing orders is still in beta. We recommend testing your imports first with a smaller sample of your file. Please let us know if you encounter any errors.
Error and warning codes that occur when dealing with product data
The mentioned product was not found on Shopify. Perhaps is has been deleted.
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.
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.
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.
File Analysis Codes
These codes will appear when you upload a spreadsheet to be imported with the app.
ALYS001 - File Does Not Exist
There was an error opening the file you uploaded. Please try again and contact us if the problem persists.
ALYS002 - Zip File Must Contains a CSV File
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.
ALYS003 - Unsupported File Type or Invalid Content
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.
ALYS004 - No Valid Sheets Found
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.
ALYS005 - Unmatched Columns
You 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 Atlera/Matrixify format. To fix this, make sure your spreadsheet matches the format in our documentation ( Product Fields for example).
ALYS006 - Shopify Export Format
It looks like you are trying to upload an export of your Shopify products to Altera. Please try uploading the file again in the Altera/Matrixify format .
ALYS007 - Unsupported Duplicate Columns
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.
ALYS008 - Invalid ID
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.
Smart and Manual Collection Codes
Error and warning codes that occur when dealing with smart and manual collections
CLTN001 - Existing Collection is a Smart Collection
The collection that already exists in Shopify is a smart collection, but the import it 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.
CLTN002 - Existing Collection is a Manual Collection
The collection that already exists in Shopify is a manual collection, but the import it 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.
File Codes
Error and warning codes for importing and exporting files.
FILE001 - Shopify Trial Limitation
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.
Job Codes
Codes related to creating and managing import or export jobs.
JOB001 - Concurrent Job Limit
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.
JOB002 - Maximum Scheduled Jobs
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.
Menu Codes
Error and warning codes for importing and exporting menus.
MENU001 - No menu items
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.
Metafield Definition Codes
Error and warning codes for importing and exporting metafield definitions.
MDEF001 - Unable to Create Metafield Definition
The Shopify API did not return a newly-created metafield definition, possibly because a matching one already exists on the store.
MDEF002 - Unable to Delete Metafield Definition
The metafield definition could not be deleted. This may be because the metafield definition was already removed.
MDEF003 - Shopify Namespaces Cannot be Modified
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.
MDEF004 - Namespace Column Missing
Please make sure that the spreadsheet you are importing include a 'Namespace' column.
Blog Post Codes
These codes are related to uploading blog posts (articles) and blogs.
BLG001 - Invalid Image URL
The image for a blog post needs to be a complete URL that starts with http:// or https://.
BLG002 - 'Blog: Handle' Column Required
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.
BLG003 - Only One Image URL Supported
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.
Object Codes
These codes occur when trying to figure out which kind of Shopify object you are importing or exporting (e.g., products, orders etc..)
OBJ001 – Unknown Export Type
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).
OBJ002 – No Matching Type
Sheet analysis didn’t find a matching type for the label. Double-check your sheet configurations or labels before importing.
OBJ003 – Unknown Import Type
You tried to import using an object slug that isn’t supported. Confirm it’s a valid import type (e.g., products, customers).
OBJ004 – Invalid Reference Handle
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.
Order Codes
Error and warning codes that occur when dealing with orders
ORD001 - ID or Name Required
All order sheets need to have either a Name or ID column to be able to group orders that span multiple rows
ORD002 - Required Column Missing
Required columns, such as the Line: Type or Line: ID column are missing from the source file.
ORD003 - Invalid Line: Type Column
The Line: Type column must be one of these values:
- Line Item
- Discount
- Shipping Line
- Transaction
- Refund Line
- Refund Shipping
- Fulfillment Line
- Ignore
ORD004 - Order Importing in Beta
Importing orders is still in beta. We recommend testing your imports first with a smaller sample of your file. Please let us know if you encounter any errors.
Product Codes
Error and warning codes that occur when dealing with product data
PRD001 - Product Not Found
The mentioned product was not found on Shopify. Perhaps is has been deleted.
PRD002 - No Option 1 Values
Products with multiple variants need to have the Option1 Value column set to identify the different variants.
PRD003 - Invalid Product Status
The product status field must be empty or one of the following: ACTIVE, ARCHIVED or DRAFT.
PRD004 - Duplicate Product Title
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.
PRD005 - Weight Should Just be a Number
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.
PRD006 - Reference Metafields Need GID Format
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.
PRD007 - Option1 Value Column Required
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").
PRD008 - Missing Option1 Value
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.
Spreadsheet Writing Codes
These codes occur when the app is writing your output to a spreadsheet
WRT001 – Unknown Object Type
You attempted to export using a data type the system doesn't recognize. Please try to reconfigure the job and run it again.
WRT002 – Unknown Export Type
The export format is not recognized. Currently Altera only supports CSV and Excel files in the Altera/Matrixify format.
Updated on: 24/04/2025