Altera shows a code such as ABC001 with each error or warning. This article explains the codes for this area of the app and how to resolve them. For codes from other areas, see Error and warning codes.
Store Migration Codes
Generic error codes for the store-migration feature that imports data from another platform into Shopify. Platform-specific issues (e.g., WooCommerce auth) use the platform's own prefix - see the sections below.
MGR001 - Unknown Migration Source
The migration's source type does not match any supported platform. This usually means the migration record was created with an outdated or invalid source_type value.
How to fix this:
Create a new migration and select a supported platform from the list.
MGR002 - Unexpected Migration Error
An unexpected error occurred while testing or running the migration. The error has been logged for investigation.
How to fix this:
Try testing the migration again. If the problem persists, contact support with the migration ID.
MGR003 - No Recognized Files
None of the uploaded files match a file the selected platform exports. Altera identifies each file by its header columns, not its name, so a file that was renamed still works, but a file from a different platform, a spreadsheet instead of a CSV, or a partial export does not.
How to fix this:
Check that you exported the files listed in the migration guide for your platform (for Magento orders: the sales order tables as CSV).
Export as CSV with a header row. Excel files are not recognized.
Upload the files again.
MGR004 - Required File Missing
Some files were recognized, but a data type is missing one of the files it needs. The error names the missing files. For Magento orders, the orders, order items, order addresses, and order payments tables are all required; shipment tracking and order history are optional.
How to fix this:
Export the missing tables and upload the complete set together (a zip of all the CSVs is easiest).
Check the Files card on the migration page to see which files were detected.
MGR005 - Upload Could Not Be Read
An uploaded file could not be used: the zip could not be opened, it contains no CSV files, the upload did not finish, or the files are larger than the migration size limit when uncompressed.
How to fix this:
Re-create the zip with a standard zip tool (on Windows, use 7-Zip rather than the built-in compressor) and make sure the CSVs are inside it.
Wait for every file to finish uploading before continuing.
For very large stores, export a shorter date range or fewer tables so the files stay under the limit.
MGR006 - File Already in the Migration
The file you added has a table or export that the migration already has from another file, for example a second orders table. A migration uses one file for each table, so Altera did not add the new file.
How to fix this:
On the migration page, remove the old file in the Files card, then add the new one.
If the new file is a zip, check that it does not hold a copy of a table that you uploaded before.
MGR007 - Files Locked While an Import File Is Created
Altera is creating an import file from this migration, and it reads the files while it does. You cannot add or remove files until it finishes.
How to fix this:
Wait until the import file is ready, then change the files.
To stop the current run, cancel its job on the job page.
WooCommerce Codes
Error codes that originate from a WooCommerce source. These are shared across all WooCommerce connection methods (REST API today, and a potential on-site plugin connector in the future).
WOO001 - Missing WooCommerce Credentials
One or more required WooCommerce credentials are missing: site URL, consumer key, or consumer secret.
How to fix this:
In your WooCommerce admin, go to WooCommerce > Settings > Advanced > REST API and generate a new key with Read permissions.
Re-enter the site URL, consumer key, and consumer secret in Altera and retest.
WOO002 - Invalid WooCommerce Site URL
The provided WooCommerce site URL is not a valid HTTP/HTTPS URL.
How to fix this:
Enter the full site URL including the scheme (e.g.,
https://example.com). Do not include a trailing slash or path.
WOO003 - WooCommerce Authentication Failed
WooCommerce rejected the API credentials. The consumer key/secret are either incorrect or lack the necessary permissions.
How to fix this:
Verify the consumer key and secret were copied correctly with no extra whitespace.
Confirm the API key has at least Read permissions in WooCommerce.
Regenerate the API key if needed.
WOO004 - WooCommerce Site Unreachable
Altera could not reach the WooCommerce site, or the site returned an unexpected error.
How to fix this:
Verify the site URL is correct and the site is online.
Ensure the site is accessible from the public internet (Altera cannot reach staging sites behind a VPN or basic auth).
Check for firewall rules, security plugins (e.g., Wordfence), or rate limits that might be blocking Altera.
If your host restricts inbound traffic by IP, allowlist
34.182.181.120(Altera's outbound IP for all migration and remote-connection traffic).
WOO005 - WooCommerce REST API Not Found
Altera reached the site but could not find the WooCommerce REST API endpoints, and could not narrow down the root cause to permalinks (WOO007) or a missing WooCommerce install (WOO008).
How to fix this:
Confirm WooCommerce is installed and activated on the site.
Confirm the WordPress REST API is not disabled by a plugin (e.g., "Disable REST API") or custom code.
Test the API yourself by visiting
https://your-site.com/wp-json/wc/v3in a browser. You should see a JSON response.Check whether
.htaccess(Apache) or rewrite rules (nginx) are routing/wp-json/*to WordPress.
WOO006 - Blocked by Cloudflare or Bot Protection
The request reached the site but was intercepted before it made it to WordPress. This can be Cloudflare, a similar service like Sucuri or Wordfence, a WAF, or bot protection built into the host's CDN (Hostinger, for example). Altera saw a challenge or block page instead of the WooCommerce REST API.
Altera identifies itself with the user agent Altera/1.0 (+https://getaltera.com) and connects from the IP 34.182.181.120, so your host or security service can allow it specifically.
How to fix this:
Allowlist Altera's outbound IP
34.182.181.120in Cloudflare, Sucuri, your security plugin, or with your hosting provider.In Cloudflare, you can instead create a WAF Skip rule for the path
/wp-json/wc/v3/*so API traffic bypasses bot challenges.If you use Wordfence or a similar plugin, whitelist
34.182.181.120in Wordfence > Tools > Live Traffic after a failed test.If your host has its own bot protection or CDN firewall, ask their support to allow requests from Altera's IP or user agent.
WOO007 - WordPress Permalinks Set to Plain
WooCommerce is installed, but WordPress permalinks are set to Plain, which disables the pretty URL routing that the REST API needs. Altera confirmed this by reaching the WooCommerce routes through the ?rest_route= fallback while the standard /wp-json/wc/v3/... path returns 404.
How to fix this:
In WordPress, go to Settings > Permalinks and choose any option other than Plain (for example, Post name).
Click Save Changes to flush the rewrite rules.
Retest the connection in Altera.
WOO008 - WooCommerce Not Installed or Activated
The WordPress REST API is reachable, but the WooCommerce namespace (/wc/v3) is not registered. The most common cause is that WooCommerce is not installed or has been deactivated on the site Altera is connecting to.
How to fix this:
Confirm WooCommerce is installed and activated under Plugins in WordPress.
Confirm the site URL in Altera matches the site where WooCommerce is installed (not, for example, a subdomain or staging URL where WC is missing).
If WooCommerce is active, check for plugins or custom code that unregister the
wc/v3REST routes.
WOO009 - Too Many Consecutive Page Failures
While paginating through a WooCommerce endpoint (for example /wc/v3/products or /wc/v3/orders), several pages in a row failed to load even after retrying. Altera skips the occasional flaky page so a single hiccup doesn't lose the whole migration, but bails out when failures stack up - that almost always indicates the source server is in trouble rather than a one-off glitch.
How to fix this:
Create the import file again once the source site has stabilized.
Check the WooCommerce site for memory/timeout errors, an overloaded host, or a security plugin rate-limiting Altera's requests.
If the issue persists, narrow the migration with a smaller date range so each request returns fewer records.
WOO010 - Pagination Appears Stuck
The WooCommerce site returned the same set of records for two pages in a row, which means the server is ignoring the page parameter Altera sends. Continuing would emit the same items over and over. This is a known issue on some WooCommerce hosting setups (see woocommerce-rest-api#60).
How to fix this:
Ask the host or site administrator to update WooCommerce - the bug is typically fixed by an upgrade.
Disable caching or security plugins (e.g. WP REST Cache, page-cache rules covering
/wp-json/) that might be serving the same response for differentpagevalues.If the migration must run before the fix, contact Altera support to retry with a smaller batch size.
WOO011 - WooCommerce Returned HTML Instead of JSON
The WooCommerce site responded with an HTML page on a REST API request where JSON was expected. The most common cause is a security plugin or server rule that redirects unauthenticated REST requests to the WordPress login page instead of returning a JSON 401. Without this guard the migration would later fail with a confusing JSON decode error.
How to fix this:
Confirm the consumer key/secret are correct and have Read access to all WooCommerce data.
Temporarily disable security plugins (e.g. Wordfence, iThemes Security, "Hide My WP") that restrict
/wp-json/access, or whitelist the Altera consumer key.Check the host's
.htaccess/ nginx config for rules that block or redirect anonymous requests to/wp-json/wc/v3/.Retry the migration once the API is reachable without a login redirect.
WOO012 - Line Item Price Rounded to 2 Decimals
WooCommerce returned a per-unit price on this line item with more decimals than Shopify supports (Shopify caps prices at 2 decimals for most currencies). Altera rounded the per-unit price to 2 decimals so the order can be imported into Shopify. The migrated Line: Price may differ from the WooCommerce source by a fraction of a cent, but Shopify recomputes the line and order totals from this value on import.
How to fix this:
No action is required. The order will import successfully into Shopify.
If the source WooCommerce line price had extra decimals because of a third-party pricing plugin (B2B tiers, bulk discounts, currency conversion), expect the per-line totals in Shopify to differ from WooCommerce by up to a fraction of a cent per line.
WOO013 - Discount: Sale-Item Exclusion Cannot Carry Over
The source coupon was configured to skip products that were already on sale at checkout. Shopify discounts always apply uniformly across whichever products match their Applies To list, regardless of whether those products are running a sale. After import the migrated discount will stack with sale pricing.
How to fix this:
If sale stacking is acceptable, no action is needed.
If on-sale products must be excluded, narrow the discount's Applies To list manually after import so it only covers products you control sale state for, or remove the migrated discount and recreate it from scratch in Shopify with the desired scope.
WOO014 - Discount: Per-Product Exclusion Cannot Carry Over
The source coupon listed specific products that the discount should NOT apply to. Shopify discounts only support a positive Applies To list (products the discount SHOULD cover), so the exclusion list cannot be honored directly. The excluded handles are kept in the Woo: Exclude products column of the discount row so you can see what was excluded in the source.
How to fix this:
Before importing, replace the discount's Applies To with the explicit list of products it should cover, derived by inverting the
Woo: Exclude productscolumn.When the exclusion list is short and the included set is large, an alternative is to keep the discount store-wide and rely on per-product overrides in Shopify (e.g. compare-at pricing or tag-based discount combinations) for the products you want to leave at full price.
WOO015 - Discount: Per-Collection Exclusion Cannot Carry Over
The source coupon listed specific product categories the discount should NOT apply to. Shopify discounts only support a positive Applies To list (collections the discount SHOULD cover), so the exclusion cannot be honored directly. The excluded category handles are kept in the Woo: Exclude categories column of the discount row.
How to fix this:
Before importing, set Applies To: Type to
Collectionsand Applies To: Values to the explicit list of collection handles the discount should cover, derived by inverting theWoo: Exclude categoriescolumn.If only one or two categories were excluded from an otherwise store-wide discount, splitting the migrated discount into two narrower discounts in Shopify is often less work than enumerating every included collection.
WOO016 - Discount: Maximum Cart Cap Cannot Carry Over
Shopify discounts can require a minimum cart amount but cannot enforce a maximum. The source coupon's cap on cart subtotal is kept in the Woo: Maximum spend column for reference, but after import the discount will apply to carts above that amount too.
How to fix this:
For caps that rarely fire in practice (e.g. a 10% off coupon capped at a very high cart amount), no action is needed.
When the cap is core to the discount's design (e.g. "first-order offer, capped at $100"), the migrated discount changes meaning in Shopify and may need to be paused or replaced with one built around the cart minimum + tighter scoping.
WOO017 - Discount: Per-Item Usage Cap Cannot Carry Over
The source coupon limited the discount to a specific number of items per order (e.g. "applies to up to 3 items"). Shopify's Limit Uses Per Order is a per-order toggle - 1 applies the discount to a single item per order, blank applies it to every item - and cannot express a fixed item count. The source value is left in the file as-is, so the cell needs editing before import.
How to fix this:
Change the
Limit Uses Per Ordercell to1if the spirit of the cap was "apply once per order", or blank if the spirit was "apply to everything that matches".If the per-item count matters (e.g. a "buy 3, save $10" mechanic), Shopify's equivalent is a Buy X Get Y discount; rebuild the discount in Shopify rather than trying to translate the source cap.
WOO018 - Order Notes Could Not Be Read
Altera couldn't fully read this order's notes from WooCommerce, so the order was migrated without (the rest of) its notes. Order notes are a non-critical detail, so rather than failing the whole migration over one order, Altera keeps any notes it already gathered, migrates the order, and flags it here. The most common cause is a WooCommerce host that ignores the page parameter on /orders/<id>/notes and re-serves the same notes (see woocommerce-rest-api#60), or a transient error on the notes endpoint specifically.
How to fix this:
No action is required if the order's notes aren't important - the order itself migrated successfully.
If you need the notes, ask the host or site administrator to update WooCommerce or disable caching/security plugins covering
/wp-json/, then create the import file again for the affected orders.The
Notecell can also be filled in manually before importing if only a few orders are affected.
WOO019 - Invalid Date Filter
One of the date filters on the migration (for example Product created on or after or Order created before) contains a value Altera can't read as a date. WooCommerce only accepts dates in the form YYYY-MM-DDTHH:MM:SS, so the value can't be forwarded as typed. The message names the filter and the value that was rejected.
Altera tidies the most common slips on its own: a year on its own (2023), a year and month (2024-06), a date without a time (2023-01-31), a time without seconds (2023-01-31T10:00), a space instead of the T, and a stray dash before the T (2023-01-31-T10:00:00). Dates written day-first or with slashes (31.01.2023, 01/31/2023) are not accepted.
How to fix this:
Enter the date as
2025-01-31T00:00:00(year-month-day, the letterT, then hour:minute:second). A date on its own, such as2025-01-31, is also accepted.Add a timezone offset if you need one, for example
2025-01-31T00:00:00+02:00. Without one, WooCommerce reads the date in the site's timezone. The customer date filters are the exception: Altera checks those itself and reads a date without an offset in your Shopify store's timezone.
WOO020 - WooCommerce Rejected the Request
WooCommerce answered a request with HTTP 400, which means WordPress rejected one of the query parameters Altera sent. The message includes WordPress's own explanation, for example Invalid parameter(s): after (after: Invalid date.). Because every page of a listing carries the same parameters, Altera stops the migration on the first rejection instead of retrying page after page.
How to fix this:
If the message names a date parameter (
after,before,modified_after, ormodified_before), correct the matching date filter on the migration and run it again. See WOO019 for the accepted formats.If the message names a parameter you didn't set, a plugin on the WooCommerce site may be altering REST requests. Ask the site administrator to check security or caching plugins that cover
/wp-json/, then create the import file again.
WOO021 - WooCommerce Returned Invalid JSON
Several pages in a row from the WooCommerce REST API weren't valid JSON, so Altera couldn't read the records. The message quotes the start of the response, which usually names the cause. The connection test can still pass, because it only reads the record counts.
Altera already ignores PHP warnings and notices printed before or after the data (for example Warning: Constant WP_CACHE already defined in wp-config.php on line 127). When you see this error, the response has other text in it or the data is incomplete, for example after a PHP fatal error, output from a plugin or theme, or a response that was cut off.
How to fix this:
Open
https://your-store.com/wp-json/in a browser. The page should start with{. If text comes before it, that text is what breaks the response.If the text is a PHP error, fix the line it names, or set
WP_DEBUG_DISPLAYtofalseinwp-config.phpso PHP messages aren't printed on the page. Your host can help with this.If the text comes from a plugin or theme, deactivate it while you create the import file.
Create the import file again.
WOO022 - Order Refunds Could Not Be Read
The order has refunds in WooCommerce, but Altera couldn't read them from the /orders/<id>/refunds endpoint, or the endpoint returned only some of them. Without its refunds, the order would be created in Shopify as paid in full, so Altera left it out of the import file. The other orders are not affected. The message includes the error from WooCommerce, which is often a timeout or a security plugin that blocks the request.
How to fix this:
Create the import file again. A temporary error usually doesn't happen a second time.
If the same orders fail again, ask the site administrator to check security or caching plugins that cover
/wp-json/, then create the import file again.
Magento Codes
Error codes that originate from a Magento source. Magento migrations read uploaded files (order table dumps and admin CSV exports), so most problems are about which files were uploaded.
MAG001 - Mixed Magento Versions
The uploaded files mix Magento 1 and Magento 2 exports. Altera tells the versions apart by their columns (for example hidden_tax_amount in Magento 1 and discount_tax_compensation_amount in Magento 2) and cannot combine them in one migration.
How to fix this:
Upload the files from one Magento installation at a time.
If you migrated from Magento 1 to Magento 2 in the past, export the tables from the Magento 2 database only.
MAG002 - Order Has No Line Items
An order in the orders table has no rows in the order items table, so there is nothing to migrate for it. The order was skipped. This usually means the items table was exported with a filter or date range that does not match the orders table.
How to fix this:
Export the full
sales_order_itemtable (orsales_flat_order_itemon Magento 1) without filters, or with the same filter as the orders table, and upload the set again.
MAG003 - Order Missing Address or Payment
An order has no billing address row or no payment row in the uploaded tables. The order was migrated with the data that was available: without a billing address the Shopify order has no billing details, and without a payment row the note has no payment method.
How to fix this:
Export the full
sales_order_addressandsales_order_paymenttables (or thesales_flat_versions on Magento 1) and upload the set again if these orders need their address or payment details.
MAG004 - Value Could Not Be Read
A value in the Magento data or in a run filter could not be read: a date filter that is not in a recognized format, or an order quantity that is not a whole number (Shopify only accepts whole quantities, so it was rounded).
How to fix this:
For a date filter, use the format
2025-01-31or2025-01-31T00:00:00.For a rounded quantity, check the line item in the output file and adjust it before importing if the rounding is not what you want.
MAG005 - Image Paths Need the Old Store URL
The Magento product export lists images as paths relative to the old store's media/catalog/product folder, not as full URLs. No old store URL was given when the migration ran, so the Image Src and Variant Image columns hold relative paths such as /media/catalog/product/m/b/mb01.jpg. Shopify cannot fetch those, so the images would be skipped on import. The warning appears once per run, on the first product with images.
How to fix this:
Create the import file again with the old store URL filled in under Options (for example
https://www.example.com). Altera then writes full image URLs.Or, in the output file, add the old store URL in front of every path in the
Image SrcandVariant Imagecolumns before you import it.The old store must stay online until the products are imported, because Shopify downloads the images from it.
MAG006 - Product Could Not Be Converted Completely
Something in a product's Magento data has no exact place in Shopify, so part of it was changed or left out. The message says what happened. Cases:
A configurable product lists a variation SKU that is not in the export. The variant was created with the option values, but its price, stock and weight were taken from the parent product.
A configurable product uses more than three attributes. Shopify products have at most three options, so the extra attributes were dropped.
Two variations have the same option values. Only the first one was kept.
A product has more than 100 images. Only the first 100 were kept.
Two products would get the same handle. The second one got a numbered handle.
How to fix this:
Check the product in the output file and adjust the variant, option, image or handle columns before you import it.
For a missing variation SKU, export all products (including ones that are not visible individually) and create the import file again.
MAG007 - Old Store URL Required for Products
The import file includes products, but the Old store URL option is empty or is not a web address. The Magento product export has only the paths of the images, so Altera needs the address of the old store to build full image links that Shopify can download.
How to fix this:
Under Options, enter the address of your Magento store, for example
https://www.example.com, then create the import file again.If you do not want to migrate products now, clear Products under Data to migrate.
Etsy Codes
Error codes that originate from an Etsy source. Etsy migrations read the CSV files from Shop Manager > Settings > Options > Download Data: the listings file for products, and the order items file (with the optional orders file) for orders.
ETSY001 - Listing Could Not Be Converted Completely
Something in an Etsy listing has no exact place in Shopify, so part of it was changed or left out. The message says what happened. Cases:
The number of SKUs in the
SKUcolumn is not the number of variants (every combination of the variation values). Etsy leaves the combinations that you do not offer out of the SKU list, so Altera cannot tell which SKU belongs to which variant. The variants of this listing have no SKU.The listing has more than one SKU but no variations. Only the first SKU was kept.
The variations make more than 2,048 combinations. Shopify allows no more variants per product, so only the first 2,048 were kept.
How to fix this:
Check the product in the output file and fill in the
Variant SKUcolumn before you import it. Order lines are linked to products by SKU, so orders for variants without a SKU are imported without a link to the product.
ETSY002 - Prices in Another Currency
The CURRENCY_CODE of the Etsy listings is not the currency of your Shopify store. Altera does not convert prices, so the prices in the output file are the Etsy amounts in the Etsy currency. The warning appears once per run, on the first product.
How to fix this:
Change the
Variant Pricecolumn in the output file to prices in your store currency before you import it.Or set the prices for other countries with Shopify Markets after the import.
ETSY003 - Value Could Not Be Read
A value in the Etsy file could not be read: a price or quantity that is not a number, a quantity that is not a whole number (Shopify only accepts whole quantities, so it was rounded), or a date that is not in a format Etsy writes (12/31/25 or 12/31/2025). The value was left out or rounded, and the rest of the product or order was converted.
How to fix this:
Check the value in the Etsy file. If the file was opened and saved again in a spreadsheet program, download it from Etsy again and upload the new file.
Or correct the value in the output file before you import it.
ETSY004 - One SKU for All Variants
The Etsy listing has variations but only one SKU, which is the SKU of the whole listing. All variants of the product got that SKU. This is information only; nothing was left out.
How to fix this:
Nothing is required. If the variants need their own SKUs, change the
Variant SKUcolumn in the output file before you import it, or in Shopify after the import.Order lines are linked to products by SKU, so an Etsy order for this listing is linked to the product, but not always to the variant that was sold.