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.
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:
Re-run the migration 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 re-run the migration 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 run the migration 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.