There can be a multitude of reasons for why an import or export didn’t go as planned. If you have confirmed that you’ve met the requirements for creating new products or updating existing products via CSV import, review the common scenarios below and their troubleshooting steps.
If you are experiencing an issue that isn’t addressed here, contact our Support team. We recommend creating a support case rather than using phone or chat support, as this allows you to attach your CSV file for our technical support representatives to review.
Always save a backup copy of your product data before making changes. This allows you to revert any missing or malformed information in your catalog.
Common Import Errors
After you import your CSV file, you are taken to a summary page which includes a log of all errors that occurred during the import process. Each error message includes the CSV line it occurred on so that you can adjust the affected data in your file.
See the table below for a list of the most common error messages and how to solve them.
| Error Message | Resolution |
|---|---|
| The product name is a duplicate |
This indicates that the product name in the "Name" field is in use by an existing product in your catalog. Add a unique product name to the "Name" field. If this error occurs on an existing product, confirm that the ID field is not blank in the Product row. |
| The display name: [Option Name] has already been used on this product | Confirm that the ID field is not blank in the variant row. This error will also occur if you’ve added new variants to a product with existing variants. |
| image_url must be present if uploading by url |
Confirm that the Image URL (Import) field is not blank or that it doesn’t contain an incomplete URL path. If this occurs on an existing image row, confirm that the ID field is not blank. |
| A duplicate product video with the video_id: [YouTube ID] was found. | This error occurs when the ID field is left blank on an existing video row, or if you’ve added the same YouTube ID more than once to a single product. |
| The custom field with the name: [custom field name] & value: [custom field value] already exists. |
This indicates that the ID is missing on an existing custom field in a Product row. Make sure that you are using the correct format for existing custom fields. This error also occurs when using the same custom field name-value combination more than once for the same product. |
| Invalid "Item" field. "[Item Value]" was provided instead of expected "Product". |
This error occurs if the Product Item value in a Product row is misspelled or not properly capitalized. To resolve this issue, make sure that the Item value on the rows indicated is "Product". This error can also indicate that your CSV file has Variant, Image, or Video rows which were not added underneath a Product row. Variant, Image, or Video rows must be located directly under the Product row they correspond to in order to import properly. |
| Invalid [field] format. [field] must be float. | This occurs if you’ve included units in a numbers-only field like Price or Weight. Remove any symbols from these fields and re-import. |
| [field] is missed. | This indicates that a field in the row was left blank. Enter information in the field, or remove the field column from your CSV file. |
| Custom field has an invalid json format. Please validate your json and try again. | The Import/Export tool uses JSON formatting for custom fields, and this error occurs when one or more custom fields in your CSV file are not formatted correctly. See the FAQ for more information. |
| API server error: code 400. | If this occurs on an image row, the server hosting the image may be blocking API access. The host will need to grant access or the image will need to be hosted elsewhere. |
Stuck Imports
If you find your imports are not completing and are becoming "stuck," there could be a few potential reasons. See the table below for a list of common scenarios and how to resolve them.
| Scenario | Resolution |
|---|---|
| Imports only stall when using a specific browser. | Clear your browser’s cache or perform the import in an incognito window. |
| Imports consistently stall after progressing to a certain percentage. |
Split up your CSV into multiple files and re-import to pinpoint which line or lines are causing the issue. Once you have identified the issue’s source and resolved it, re-import your data. |
| Imports stall when using a CSV of products with numerous images. |
Check that your CSV file contains fewer than 1,000 images. Optimize images with larger dimensions or file sizes. |
| The import stalls after too many product images fail to upload. | Confirm that your image URLs are publicly accessible. If you are hosting your images in WebDAV, make sure to copy the URL that does not contain /dav. |
| The CSV contains base64 encoded images or malformed HTML in the Product Description column. |
Use HTML markup instead of base64 coding to add images to product descriptions. Check for HTML formatting issues in product descriptions, or exclude the Product Description column from your CSV file. |
| Text fields, such as SKU or Page Title, exceed their character limits. | Check the field’s details in Supported Product Fields to confirm they aren’t exceeding character maximums. |
| ID column values don’t correspond to the data (products, custom fields, variants, images, and videos) in the line. |
Export a separate CSV of your products and cross-reference for any mismatched IDs in your import file. When creating new products, leave the ID value blank. |
SKUs in Scientific Notation and Missing Special Characters
When opening an exported CSV file, you may experience an issue in which your spreadsheet program automatically converts numerical product identifiers, such as SKUs or UPCs, to scientific notation. Your program can also remove leading zeros or unique characters from text. We’ve provided instructions on formatting your CSV file to resolve this issue in the following spreadsheet programs:
Microsoft Excel
Since Excel will automatically make these changes when the file is opened, it is best to remove this formatting before loading your CSV file into Excel. Note that these steps will only load your current CSV in Excel. You must perform these steps for each new CSV.
These steps are for Excel 2022, but the process is similar for other versions. You may also want to consider removing the SKU column from your CSV file whenever you do not require SKUs for product update or recordkeeping.
1. Open a blank Excel Workbook and go to Data › From Text/CSV.
2. Select your export file and click Import, then click Transform Data.
3. In the Query Settings on the right, deselect Changed Type by clicking X.
4. Click Close & Load in the upper left. Your data will appear with correctly formatted numbers. Note that Excel will format your data as a "Table," but you can edit the display settings in Table Design if needed.
Google Sheets
In addition to Excel, you can use Google Sheets to edit your CSV files. To open your CSV file, go to File › Import in Google Sheets.
After selecting your file, uncheck the box next to Convert text to numbers, dates, and formulas. This ensures that any leading zeros or unique characters are maintained upon import. Additionally, confirm that your separator type is set to Comma.
Click Import data to open your CSV file in a new spreadsheet.
Using Delimiter Characters
Some special characters are used to distinguish specific items, such as individual categories or options. These characters are called delimiters or field separators, and they can cause missing or malformed data if they are used incorrectly in CSV files.
The modern Import/Export experience uses commas (,) as delimiters. While this does not affect how you can use commas in fields like Options or Custom Fields, it means that opening your CSV file in a spreadsheet program like the Numbers app, which uses other characters as field separators, will cause formatting issues.
While not a delimiter, the Custom Fields column uses double quotes (" ") as a field enclosure. If you want to add a custom field with quotation marks in its name or value, you must use the HTML character code for quotation marks (") in order to prevent import errors.
For example, if you wanted to add a custom field of Color: "Blue" to your product, you would format it in your CSV file like this: [{"name":"Color","value":""Blue""}].
FAQ
Why am I getting the error "No products selected" while exporting products?
If you haven’t selected any products for export or if there aren't any products in your store's catalog, you will be unable to start an export. Go to Products › View and select which products you want to export, then restart the export.
Why am I getting the error "Custom field has an invalid json format. (Data decoding failed: Syntax error.)"?
The Import/Export tool uses JSON formatting for custom fields, and this error occurs when one or more custom fields in your CSV file are not formatted correctly. Review the custom fields in the rows identified within the error log to make sure they meet the formatting requirements.
This can also occur if you use smart or curly quotes (“ ”) instead of straight quotes (" ") to wrap your custom field elements. See the examples below for a comparison of the supported and unsupported quote format.
Supported Example
[{"id":6,"name":"Color","value":"Blue"},{"id":7,"name":"Material","value":"Cotton"}]
Unsupported Example
[{“id”:6,“name”:“Color”,“value”:“Blue”},{“id”:7,“name”:“Material”,“value”:“Cotton”}]
If your spreadsheet program automatically converts straight quotes to smart quotes, you will need to update your program’s preferences to use straight quotes by default. Reference your spreadsheet program's help documentation for steps on changing the default quote format.
Why are my product images not importing?
Confirm that your image meets the requirements for import.
If you are seeing API server error: code 400 in the Error log, the server hosting the image may be blocking API access. The host will need to grant access or the image will need to be hosted elsewhere.
