While using the correct headers and field formatting in your CSV file is important for mitigating inaccurate or missing product data, there are a variety of factors that can contribute to a faulty import. 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 and troubleshooting steps in this chapter.
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. See Backing Up Your Store for more information.
Common Import Errors
After completing a product import, the import summary includes reports for products that partially or fully failed to import, as well as duplicate products that were not imported. Click More information to open a report that includes the CSV row where the error occurred and a descriptive error message.
In the table below, we’ve included the most common errors that occur during import, along with tips on resolving them.
| Error Message | Resolution |
|---|---|
| A product with the specified ID was not found |
This indicates that the Product ID value does not correspond to an existing product. For existing products, confirm the correct product ID in your control panel by editing the product and viewing the ID value in the URL. Example: https://store-abc123.mybigcommerce.com/manage/products/edit/123 For new products, leave the Product ID field blank. |
| Every Rule must have either Product Name or Product Code/SKU data |
This indicates that the Product Code/SKU value on the Rule row is missing, or doesn’t correspond to an existing variant SKU. Add or correct the variant SKU to resolve the issue. If the Rule row corresponds to a product modifier, confirm that the Product Name value meets the formatting requirements. |
| The product image does not exist |
Confirm that your image files are in the product_images/import folder of WebDAV. If you are importing product images via URL, confirm that the URL is publicly accessible and uses HTTP or HTTPS. If you are seeing this error on all products, confirm that you have matched the Product Image File field to the corresponding column header in your CSV file while importing your products. |
| The server may be down or your site is blocked from accessing it | If the URL in the Product Image File field is publicly accessible, 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. |
| The product file does not exist |
This is an expected error if you are importing existing digital products, and it indicates that your product files were not duplicated upon import. If you are importing digital products for the first time, confirm that you added your digital files to the product_downloads/import folder of WebDAV, and that the spelling of the filename is correct. |
| Custom field keys must have a value | This error occurs when the Import/Export tool cannot recognize the name-value formatting of a custom field. Make sure your custom fields are entered as name=value, and that multiple custom fields are separated with a semicolon (like Color=Blue;Material=Cotton). |
| The Product was imported successful but an error occurred while trying to save the URL for this item | This indicates that the Product URL field is not formatted correctly. Use the following format: /product-url/. |
| Uploaded file must be of type 'csv' |
Confirm that the file extension is .csv. The Firefox browser has limitations with detecting file extensions. If you are using Firefox, use another browser, such as Chrome, Safari, or Edge to import your file. |
| Runtime Exception | Contact our technical support team for assistance. |
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. |
| Data exported using a custom export template stalls upon re-import. | Use the Bulk Edit template to export and re-import your data. |
| Import page goes blank after clicking Next. |
If your CSV file has a high number of blank columns, delete any unused columns before importing. A high number of blank cells within columns can also be a cause. |
| Imports consistently stall after progressing to a certain percentage. |
Split up your CSV file into multiple smaller files, then 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. If your CSV file has a high number of blank image columns, delete any unused columns before importing. |
| The import stalls after too many product images fail to upload. |
Make sure that the image names and extensions (such as .png or .jpg) match the case-sensitive names and extensions in WebDAV. If you are uploading product images via URL, make sure that the URLs are publicly accessible. |
| 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 Product Code/SKU or Page Title, exceed their character limits. | Check the length of your text fields against BigCommerce’s platform limits to confirm they aren’t exceeding character maximums. |
| ID column values don’t correspond to the data in the line. |
Export a separate CSV file of your products, and cross-reference for any mismatched IDs in your import file. When creating new products, leave the ID value blank or exclude the ID column entirely. |
| The import is stalled due to formatting errors caused by delimiter characters. | Confirm that any delimiter characters present in your CSV file are being used properly. See Using Delimiter Characters for more information. |
SKUs in Scientific Notation and Missing Special Characters
When opening an exported CSV file, you may experience an issue where the Excel spreadsheet program automatically converts long SKUs or UPCs to scientific notation. Excel can also remove leading zeros or unique characters from text.
If you are experiencing these problems, we’ve provided instructions on formatting your CSV file to resolve this issue in the following spreadsheet programs:
Microsoft Excel
Since Excel will automatically convert long numbers to scientific notation 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 file in Excel. You must perform these steps for each new CSV file.
These steps are for Excel 2022, but the process is similar for other versions. You may also want to consider creating a custom export template without SKUs to use whenever you do not require SKUs for product updates 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.
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, and they can cause missing or malformed data if they are used incorrectly in CSV files.
For example, exporting a product with two color variants, Finish: White and Finish: Black, and then re-importing it will create a third variant (Finish) due to the colon in the variant names.
The table below contains all delimiter characters used in CSV file imports and the affected import fields.
| Delimiter Character | Affected Fields |
|---|---|
| Comma (,) | Used as a general delimiter in all CSV fields. |
| Semicolon (;) | Categories, Channels, Search Keywords, Meta Keywords, Custom Fields, Options |
| Colon (:) | Options |
| Vertical bar (|) | Custom Fields, Options |
| Equal sign (=) | Custom Fields, Options |
| Square Brackets ([ ]) | Options |
Delimiter characters can be used in the following CSV fields if they are contained in quotation marks (" "), such as “Finish: White”:
- SKU
- Description
- Page Title
- Meta Description
- Search Keywords
- UPC
- GTIN
- BPN
- MPN
- Warranty
FAQ
Is my data being exported in scientific notation from BigCommerce?
No. All data is exported in a comma-separated value (CSV) file, which allows data to be saved in a table structured format. Traditionally, they take the form of a text file containing information separated by commas, hence the name. The scientific notation conversion happens when your spreadsheet program opens the CSV and applies formatting to long number values.
How do I use numbers in other columns?
If you have other number-based columns that need to be recognized as numbers so that you can execute functions in your spreadsheet program, highlight the column and change the number format to Number or General. This option will convert your column without affecting other columns in your CSV file.
Why are some product fields combined into a single column?
Certain attributes, such as product images and digital files, have multiple sub-items that can be viewed and edited in the CSV file. By default, the Bulk Edit template separates these into individual rows, but a custom export template will display sub-items in a single column if the template’s settings are configured to Combine sub items into one field.
Select one of the other options in the Sub Items dropdown to display each sub-item individually.
Why are my digital product files being duplicated upon import?
When exporting existing digital products, the Product File column includes the filename and extension of all digital files. If these files are present in the product_downloads/import folder of WebDAV, they will be recreated on the corresponding products. To prevent duplicates, remove all files from the product_downloads/import folder after successfully importing them.
