How to Troubleshoot Wix CSV Upload Errors

(Updated 29th June 2026)

Seeing the "Products with Errors" message after uploading your Wix CSV can be frustrating, especially when you're not sure where to start. The good news is that most CSV errors are caused by small formatting mistakes, spelling errors or hidden characters, and many can be resolved with just a few simple changes.

This guide walks through the most common Wix CSV upload errors using real examples, explaining what each error means, why it happens, and the steps needed to fix it. In many cases, you'll discover that one small correction removes several error messages at once.

Before you start troubleshooting

Before working through the errors below, take a moment to check that your CSV is built on the correct foundation.

Can you answer Yes to all of these questions?

• Did you start with the official Blank Wix CSV Template downloaded from your Wix dashboard?
  

• Have you kept all of the original column headings exactly as they appear in the template?
  

• Are you editing the Wix template rather than trying to upload a CSV exported from another eCommerce platform?
  

• Has the file been exported or saved as a .csv file before uploading?
  

If the answer to any of these questions is No, it's worth stopping here before troubleshooting individual errors.

Many CSV files exported from platforms such as Shopify, WooCommerce, Squarespace or Etsy use completely different column structures and field names. Although they may look similar in a spreadsheet, they aren't compatible with Wix and can't simply be uploaded without first being converted into the Wix CSV format.

If that's the situation you're in, we recommend reading The Ultimate Guide to Bulk Importing Products into Wix Using a CSV File first. It explains how to build a Wix-compatible CSV from the ground up and will save you a great deal of time before you begin troubleshooting.

Let's work through each error one step at a time and get your products uploaded successfully.

If you've just uploaded your CSV and been presented with the "Products with Errors" message, here's how to troubleshoot each issue.

Error: handleId: HandleId must be unique for each product

This is one of the most common Wix CSV upload errors, and fortunately, it's usually one of the quickest to fix.

The error means Wix has found the same handleId assigned to more than one Product. Every product in your CSV must have its own unique handleId; otherwise, Wix can't tell where one product ends and another begins.

If you'd like to learn more about how handleId works, take a look at our dedicated guide: What are handleId and fieldType in a Wix CSV?

Finding the problem

One of the most helpful things about Wix's error reporting is that it tells you exactly where to start looking.

In the example above, Wix reports:

Row 2 – Bone China Mug

That doesn't always mean the mistake is in Row 2. It simply means the error relates to that product, so we'll use it as our starting point.

Let's take a look at the CSV.

Troubleshooting

At first glance, Row 2 looks perfectly normal.

The handleId is mug1, the product has a name, a description and all of the expected information. Nothing immediately stands out as being incorrect.

Looking a little further down the spreadsheet, you'll notice that Rows 3, 4 and 5 also use the handleId mug1.

That isn't a problem on its own; those rows are Variants, and every variant should share the same handleId as its parent Product.

The real problem appears in Row 3, although it's intended to be a variant, the fieldType has been entered as Product instead of Variant.

Because Wix now thinks two separate Products are using the same handleId, it reports the duplicate identifier error.

How to fix it

Simply change the fieldType in Row 3 from Product to Variant.

Once you've made that change, Row 2 becomes the only Product row, while Rows 3, 4 and 5 are correctly recognised as its variants.

Wix Doctor tip: Don't rush through the entire list of errors. Correct the first error, save your CSV and upload it again before moving on. One small change can often resolve several other errors automatically, as you'll see in the next example.

Multiple errors caused by the same problem:

After correcting Row 3, Wix originally reported several more errors for the same row:

• Required Field - price is missing

• productOptionType1: Must be either "COLOR" or "DROP_DOWN"

• Required field - name is missing

• Required field - productOptionName1 is missing

At first glance, it looks as though there are several more problems to fix.

In reality, every one of these errors was caused by the same mistake we corrected in the previous section.

Let's look at why.

Required field – price is missing

This error was technically correct because Row 3 was incorrectly labelled as a Product; Wix expected it to contain a price.

After changing the fieldType to Variant, that requirement no longer applies because variants inherit their pricing from the parent product and use the surcharge field when necessary.

productOptionType1: Must be either "COLOR" or "DROP_DOWN"

This is another error that only applies to Product rows.

The productOptionType1 field defines the available options for the product and is only completed once on the parent Product row.

After changing Row 3 to a Variant, this error disappears automatically.

Required field – name is missing

Exactly the same principle applies here.

• A Product row must contain a product name.

• A Variant row doesn't require one because it inherits the name from its parent Product.

Required field – productOptionName1 is missing

Once again, this field only belongs on the Product row, and since Row 3 is now correctly identified as a Variant, there's nothing to fix.

What we've learned

Although Wix originally displayed several different error messages, they all stemmed from a single incorrect value in the fieldType column.

By correcting one cell, every one of these errors was resolved without making any further changes to the CSV.

Wix Doctor tip: Always look for the root cause before fixing errors one by one. When several errors appear on the same row, they're often symptoms of one underlying problem rather than separate mistakes.

Errors:

handleId: Variant must have the same "handleId" as its product

surcharge: Surcharge number is not valid

So let's take a look at Row 4 and see what's going on here.

Looking at the CSV, Row 4 appears to be correct. The handleId is mug1, which matches the product, and the surcharge is 4, which is a valid number.

So why is Wix still showing an error?

This is another example of the same root problem from Row 3.

Because Row 3 was incorrectly set as a Product, Wix treated it as the start of a new product group. That interrupted the connection between the parent product and the following variants.

Once Row 3 is changed from Product to Variant, Wix can read the product group correctly again. The handleId error disappears, and the surcharge value is recognised as valid.

What we've learned so far

At this point, we've resolved multiple error messages by changing just one cell: the fieldType value in Row 3.

That's why it's so important to work through CSV errors methodically. A long list of error messages doesn't always mean your spreadsheet has dozens of separate problems. Sometimes, one incorrect value causes a chain reaction across several rows.

Wix Doctor tip: When several errors appear close together, check whether they all relate to the same product group before making lots of changes. One correction near the top of the group can often fix the rows beneath it.

Error

productOptionDescription1: Incorrect option choice

Row 5 shows three errors, but two of them have already been resolved by correcting the fieldType issue in Row 3.

The remaining error is:

productOptionDescription1: Incorrect option choice

At first glance, the row looks correct. The option value is Large, and it appears to match the option listed on the Product row.

When this happens, the next step is to inspect the cell more closely.

In this example, the problem is an extra space after the word Large. This is what we call an invisible error. You may not notice it while looking at the spreadsheet normally, but Wix still reads it as part of the value.

That means Large and Large are treated as two different option choices.

To fix the error, remove the extra space at the end of the value in Row 5.

Wix Doctor tip: If an option looks correct but Wix says it doesn’t match, click into the cell and highlight the full value. Hidden spaces before or after the text are one of the most common causes of Incorrect option choice errors.

Error

productOptionType1: Must be either "COLOR" or "DROP_DOWN"

This error may look familiar.

Earlier in the guide, we saw the same message, but it was caused by an incorrect fieldType. This time, the cause is completely different.

Let's look at Row 6.

As soon as we inspect the productOptionType1 cell, the problem becomes clear.

The value has been entered as DROP-DOWN instead of DROP_DOWN.

It's a very small difference, but Wix only accepts two values in this field:

• COLOR

• DROP_DOWN

Any variation, including different punctuation, spacing or spelling, will trigger an error.

To fix the problem, simply replace DROP-DOWN with DROP_DOWN and upload the CSV again.

Wix Doctor tip: Don't assume the same error message always has the same solution. Wix validates each row independently, so identical error messages can be caused by completely different mistakes elsewhere in your CSV.

Error

fieldType: Must be either "Product" or "Variant"

This error appears when the fieldType value doesn't exactly match one of the two accepted options:

• Product

• Variant

In this example, the error appears on both Row 7 and Row 8.

At first glance, both rows look correct. The words Product and Variant appear to be spelled correctly, so the next step is to inspect the cells more closely.

Using the same method as before, highlight the full value inside each affected cell. In this case, both errors are caused by an extra space after the word.

This can easily happen when copying and pasting values from another row, especially if the original cell already contained a hidden space.

To fix the error, remove the extra space from the fieldType cells in Row 7 and Row 8, then save and re-upload your CSV.

Wix Doctor tip: When fixing hidden spaces, check the original cell you copied from as well as the rows showing errors. Copying one incorrect value can spread the same issue across several rows.

Error

productOptionType1: Must be either "COLOR" or "DROP_DOWN"

Yes... This error again!

We've already seen this message twice in this guide, each time with a different cause. This example is another reminder that the same Wix error can have several possible solutions.

This time, the problem is simply a spelling mistake.

The value has been entered as COLOUR, using the British spelling, instead of COLOR, which is the only spelling accepted by the Wix CSV template.

Although Wix is available in British English, the CSV template follows programming conventions and uses the American spelling COLOR. Any other variation, including COLOUR, will trigger this validation error.

To fix the problem, change COLOUR to COLOR, save your CSV and upload it again.

Wix Doctor tip: If your browser, spreadsheet application or operating system uses British English, keep an eye on spellcheck and autocorrect. They can automatically change COLOR to COLOUR, introducing an error without you noticing.

Discovering Additional Errors

You've corrected every error in the original list, saved your CSV and uploaded it again.

Everything should work now... right?

Not necessarily.

It's quite common for Wix to display a new list of errors after you've fixed the first set. Although that can feel frustrating, it's actually a good sign.

Earlier in this guide, we saw how one incorrect fieldType value created several different error messages. The opposite can also happen. One error can prevent Wix from validating the rows that follow, meaning some problems aren't discovered until the first issue has been resolved.

In this example, that's exactly what happened.

After correcting the original errors, Wix reported a new set of issues, all relating to the productOptionDescription1 column.

Let's start with Row 8.

Looking at the value in productOptionDescription1, we can see that Medium has an accidental comma after it.

Because the option no longer matches the value defined on the Product row, Wix reports it as an invalid option.

To fix the error, simply remove the comma so the value exactly matches the original option.

Wix Doctor tip: Don't be discouraged if a second round of errors appears after uploading your corrected CSV. It usually means you've successfully resolved the earlier problems, and Wix is now able to validate more of your spreadsheet.

Moving on to Rows 12, 13 and 14, everything appears to be correct at first glance.

The available options are defined as White;Red;Blue, and each Variant has been assigned one of those values exactly as we'd expect.

So where's the problem?

When several rows produce the same error, it's often a clue that they all share the same underlying cause.

In this case, Rows 12, 13 and 14 all belong to the same parent product in Row 11. Even though Wix hasn't reported an error on Row 11, that's the first place I'd investigate.

This is an important troubleshooting technique. The row showing the error isn't always the row containing the mistake. Sometimes the error originates in the parent Product row, with every Variant beneath it simply reflecting the problem.

Let's take a closer look at Row 11 and see what Wix has found.

Wix Doctor tip: When several Variant rows report the same error, always inspect the parent Product row before editing each variant individually. One correction on the parent row can often resolve every related error in the group.

And that's exactly where we'll find another invisible error.

Take a close look at the productOptionDescription1 cell in Row 11.

Can you spot it?

There's a tiny extra space after the word Blue. It's another one of those invisible errors that can be almost impossible to notice until you click into the cell or highlight the text. Even though it looks correct at first glance, Wix treats Blue and Blue as two completely different values.

But we're not finished yet, there's a second problem hiding in the same cell, and this one will also prevent the CSV from uploading successfully.

Did you spot it?

The productOptionType1 field for this product is set to COLOR, which means the option values can't simply be

White;Red;Blue

When using COLOR, every option must include both the HEX colour code and the colour name using the following format:

#FFFFFF:White;#FF3131:Red;#5271FF:Blue

Once the extra space has been removed and the option values have been converted to the correct COLOR format, the related errors for the variants will be resolved.

Wix Doctor tip: Always check that your productOptionDescription1 values match the selected productOptionType1. If you're using COLOR, every option must include a HEX colour code as well as the colour name.

This is explained in full in the article What is the Difference Between Products and Variants?

Creating an Error-free CSV to Upload to Wix

After working through the validation errors, it's time to upload the CSV again.

Success!

This time, the CSV passes Wix's validation checks and is accepted for import.

Then another message appears...

Product image couldn't be uploaded. Please try uploading your image again.

Don't panic.

This isn't another CSV validation error. Your spreadsheet has already passed those checks. Wix is now trying to import the images referenced in your productImageUrl column, and one of those image references has failed.

If your catalogue only contains a few products, manually uploading the missing image might be the quickest solution.

For larger catalogues, however, it's worth finding the underlying problem so that every image imports correctly.

Click Review now in the error message to see which product has been affected.

In this example, Wix tells us the problem belongs to the Bone China Plate, so we can return to the CSV and inspect the image URLs for that product.

Finding the mistake isn't always easy; image URLs are often long strings of text, making tiny formatting errors difficult to spot.

In this case, the problem is a single punctuation mark. Instead of separating two image URLs with a semicolon (;), a colon (:) has been used.

It's an incredibly small mistake, yet it's enough to stop Wix from reading the image list correctly.

Replace the colon with a semicolon, save the CSV and upload it again.

Wix Doctor tip: When troubleshooting image imports, compare the punctuation carefully. A single incorrect character in a long URL is much easier to miss than a spelling mistake, especially when several image URLs are stored in the same cell.

Updating products with a new CSV

At this point, your products have already been imported into Wix, but one of the image URLs still needs correcting. Does that mean you have to delete everything and start again? Thankfully, no.

One of the biggest advantages of using a CSV is that it isn't just for importing products. It's also an excellent way to update them.

Because every Product and Variant has its own handleId, Wix can recognise products that already exist in your store. When you upload a corrected version of the same CSV, Wix matches each row using the handleId and updates the existing products instead of creating duplicates.

In this example, we simply correct the image URL, save the CSV and upload it again. Wix updates the existing product with the corrected information while leaving the rest of the catalogue unchanged.

Wix Doctor tip: Never change a product's handleId if your intention is to update an existing product. Changing the handleId tells Wix it's a completely new product, which can result in duplicate listings instead of updating the original.

Have you managed to create an error-free CSV?

If you've followed this guide from start to finish, you've worked through many of the most common Wix CSV upload errors and, more importantly, learned how to troubleshoot them systematically.

The biggest lesson is that error messages should rarely be viewed in isolation. One incorrect value can generate several different validation errors, while fixing one problem often reveals another that Wix couldn't detect beforehand. Working through the errors one at a time and understanding what each message is telling you will almost always lead you to the solution.

You'll also have seen how seemingly insignificant details, such as an extra space, a misplaced punctuation mark or an incorrect spelling, can prevent an otherwise well-structured CSV from importing successfully. Taking a methodical approach and checking each value carefully will save you a great deal of time when working with larger product catalogues.

Even after a successful import, your CSV can continue to be a valuable management tool. If you need to make changes in the future, use the Export your physical products to a CSV file option in your Wix dashboard to download the latest version of your catalogue before making any edits.

This ensures you're working with the most up-to-date product data, including inventory changes, manual edits, updated images and any other information that may have changed since the original import. Once you've made your updates, save the file as a CSV and upload it again. As long as the handleId values remain unchanged, Wix will recognise the existing products and update them rather than creating duplicates.

Thank you for reading this guide. I hope it's helped you understand not only how to fix common CSV errors, but also how to approach troubleshooting with confidence.

Guest author

This article was written by Wix Doctor, a specialist Wix support service providing technical help, troubleshooting and advanced solutions for Wix websites.

If you'd like to build a Wix-compatible CSV from the ground up, continue with The Ultimate Guide to Bulk Importing Products into Wix Using a CSV File. It covers every field in the Wix CSV template, from product options and pricing to images, categories, inventory and much more.