top of page

How to Troubleshoot Wix CSV Upload Errors

Updated: Feb 20

"Products With Errors" Ergh! CSVs! Am I right? If you've ever found yourself stuck, staring at a screen filled with error messages while trying to upload a product CSV file to your Wix store, you're not alone. This is a common challenge many Wix users face, but the good news is that it's often easier to fix than you might think.


In this blog post, we'll dive into the most common issues that arise during the CSV upload process on Wix. From formatting woes to data mismatches, we'll cover a range of scenarios that might be causing your upload to falter. More importantly, we'll provide you with step-by-step solutions to these problems, ensuring that your product data gets uploaded smoothly and efficiently.


Whether you're a seasoned Wix user or new to the platform, this guide is designed to help you navigate through the intricacies of CSV file uploads. So, let's get started and turn those frustrating error messages into a thing of the past!


If you need an expert eye to help you through your Wix CSV errors why not book our 45-minute Zoom coaching session where we work through the errors with you and help you finally master the Wix CSV upload process or use our full done for you service and we'll take care of the entire upload process for you!


Man annoyed with his head on a computer

Man celebrating at his computer, banner ad for NX Digital's Wix CSV product upload service

How to Troubleshoot Wix CSV Upload Errors

If you are in the process of uploading your CSV and you have seen this "Product With Errors" message, here's how to fix it:


Error: handleId: HandleId must be unique for each product


Error: handleId: HandleId must be unique for each product

You can find out more about handleId in this blog post, but this one is relatively easy to fix.


This error comes up when an identical handleId has been used for more than one product. But how do we know where to find the error on the CSV?


Thankfully, Wix tells us where the error can be found, you will see in the image above that it specifies Row 2, Product Bone china Mug. So let's take a look at the CSV and see if we can identify the problem...


Error: handleId: HandleId must be unique for each product

Troubleshooting steps:

  1. Row 2 shows the handleId of mug1 which is a product, and has a name, description etc... This all looks correct, we can't see any errors here, so what's the problem?

  2. You will notice that rows 3, 4 and 5 all have the same handleId of mug1, that's because they are variants.

  3. Notice in row 3, under fieldType, we can see it is listed as a Product. There's the problem!

To fix this error, have to change the field type in row 3 to Variant. Row 1 then becomes the only Product row, and the Variants are all listed correctly


Error: handleId: HandleId must be unique for each product

Errors:

Required Field - price is missing

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

Required field - name is missing

Required field - productOptionName1 is missing


Errors: Required Field - price is missing productOptionType1: Must be either "COLOR" or "DROP_DOWN" Required field - name is missing Required field - productOptionName1 is missing

The second error on the list showed 5 different errors, but we just edited row 3 during the troubleshooting of row 2. Let's take a look at each error and see if we need to take further action:


Required Field - price is missing


This error happens because Wix thinks row 3 is a Product, so the error was correct. All products require a price.


However, we have already changed Row 3 to a Variant, and variants don't require a price. So this error has been fixed already.


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


Again, this is true. All products with options must have either COLOR or DROP_DOWN if there are variant options listed with the same handleId. But, this no longer applies because we have changed the Product to a Variant and these fields are not required for Variants.


Required field - name is missing

Required field - productOptionName1 is missing


The same applies to the remaining errors. They are only applicable if the row is a Product row.


So, we can conclude that we don't need to take any trouble shooting steps for the errors in Row 3 because we fixed them all with one simple change that was related to the incorrect naming of Products and Variants in the fieldType column!


Errors:

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

surcharge: Surcharge number is not valid


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.


Errors: handleId: Variant must have the same "handleId" as its product surcharge: Surcharge number is not valid

It all looks correct, the handleId is mug1 and the surcharge is 4, which is a valid number to use. So what could the problem be?


Yes, you guessed it! this error was also caused by the incorrect use of fieldType in row 3, and here's why. Because we had Row 3 set to Product, with no price, the surcharge wasn't recognised.


Let's have a moment of reflection, we have looked at and solved 8 errors already, and all we have changed is one cell, the fieldType of row 3. Errors don't have to be confusing or overwhelming. If we work through them systematically, we can often solve multiple errors with just one change.


Error

productOptionDescription1: Incorrect option choice


Error productOptionDescription1: Incorrect option choice

Row 5 shows 3 errors, but we already know that handleId: Variant must have the same "handleId" as its product and surcharge: Surcharge number is not valid are solved already, so we only need to look at productOptionDescription1: Incorrect option choice.


Error productOptionDescription1: Incorrect option choice

It looks correct on the first inspection, we have correctly filled in all fields. If you are unsure how to do this, you can learn all about the differences and creating product options in this article, What is the Difference Between Products and Variants?


So what could the problem be? The error tells us that Row 5 has a problem in the productOptionDescription1 cell, which would be where we have written Large. It looks correct, and it is spelt the same way it is in Row 2, so let's inspect the cell on the CSV itself.


Error productOptionDescription1: Incorrect option choice

I highlighted the contents of the cell, and can you spot what the issue is?


It's got a space after the word Large! This is what I call an invisible error. It would have been impossible to spot this error just by looking at the CSV. I had to highlight the contents to identify the problem, and even then it is still hard to spot. This is an example of how precise you have to be when working with CSVs.


CSV is an acronym for Comma Separated Values, (which ironically is a bit of a misnomer, because we use semicolons to separate values), so it doesn't recognise spaces as a value or a separator.


To fix this error, we simply have to remove the space at the end of the word Large in row 5!


Error

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

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

Does this sound familiar? Yep, that's right, we saw this error in Row 3, but we're getting it for a different reason this time. Let's take a look at Row 6 and see where we've gone wrong.


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

This one is a bit more obvious than the last invisible error, you can see that it says DROP-DOWN instead of DROP_DOWN. Again, a very tiny error, but one that stops your upload from being successful.


Error

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

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

This error has come up for both row 7 and row 8. To troubleshoot this, I followed the same process as we did for row 5, and as you can see in the screenshot below, both errors are caused by the invisible space! To fix this, we just remove the space after each word.


This could have occurred if I used copy/paste, and accidentally copied a cell that already had an error in it.


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

Error

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


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

Not this error again! I'm sure you will remember that we have already fixed this twice, so could it be the same reason again or is there some other reason we could get this error?


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

It's a misspelling this time! I'm in the UK, and we spell it colour here. CSVs, and all of the computer code languages use the American spelling of COLOR, this error can be very common, especially if you have a spellchecker or autocorrect that automatically fixes your spelling mistakes as you go along. This one is a simple fix, just change the spelling to COLOR.


Discovering Additional Errors


Ok, so we worked our way through the original list of errors, fixed all of the problems, and tried uploading the CSV again. Should be fine right? After all, we fixed all of the errors.


Don't be surprised if you get a new list of errors. Just like we saw at the start, where one mistake in the fieldType column caused 6 different errors that were all fixed with a single change, the same can happen the other way. One of our existing errors may have stopped others from being found.


In the case of this file, we did get a new list of errors, here they are:


Discovering Additional Errors

It turns out these are all to do with the productOptionDescription1 columns, the same ones, that we previously fixed an error on.

Discovering Additional Errors

So let's take a look at row 8, we can see that under the productOptionDescription1 column, the word Medium has a comma after it. That's row 8 solved!


Discovering Additional Errors

Moving on to rows 12, 13 and 14. Everything looks fine. We have got the product options White;Red;Blue and then specified in the Variants which one is which.


Here's what we can assume, because we have an identical error in rows 12, 13 and 14, the error is most likely caused by the same thing. One thing they all have in common is that they are all related to row 11. Even though the error is not listed in row 11, that's where I think we should look for the problem.


Discovering Additional Errors

And that's exactly where we will find another invisible error! Can you see it? the tiny extra space after the word Blue. Watch out for these pesky invisible errors!


But, there's another problem here that will cause an error and stop the uploads! Did you spot it? These are the wrong option choices when we use COLOR in the productOptionType1 column.


When we use the COLOR option, we must specify the HEX codes for the colours. Here's the correct way to do it.


Discovering Additional Errors

This is explained in full in an article I previously published called What is the Difference Between Products and Variants?


Creating an Error-free CSV to Upload to Wix


The time has come for us to try uploading the CSV again, hopefully error-free this time!


Creating an Error-free CSV to Upload to Wix

Success! The CSV has passed the checks and is ready to upload. But wait.... Uh Oh... Not another error message!


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


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

Just when we thought we had it, it turns out there's a problem with one of the images. This is a small upload with only a few images, so I could just find which product it is, and manually upload the image that failed. But what if you have hundreds or thousands of images, manually adding them is not an option.


We can click on the review now button that came up with the error, and start to work out which image is the problem.


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

We can see here that the image with an error belongs to the bone china plate, so let's head back to our CSV and find the error.


It took me a while to find this one, it's so small, and hidden amongst all of the Image URLs, can you spot it? I used a colon instead of a semicolon! Remember, accuracy and precision are key.

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

Overwriting a Product Collection With a New CSV


We've found ourselves in a bit of a situation here, we have already uploaded the CSV, and the products are uploaded to the store, but now we need to make changes to the image URLs. What do we do?


The beauty of CSVs is that we can make changes to them, and upload them again. Because each Product and Variant has a unique handleId, Wix knows that they are the same product and won't create duplicates. It will simply update the products with the most up-to-date data from the latest CSV that is uploaded.


Have you managed to create an error-free CSV?


Troubleshooting CSV upload errors on Wix can initially seem daunting, but as we've demonstrated, many of these errors can be resolved with careful attention to detail and a systematic approach. From correcting invisible errors like extra spaces to ensuring proper field types and spellings, the key is precision and understanding the specific requirements of Wix's CSV format.


Remember, the most common issues usually revolve around handleId's, fieldTypes, product options, and formatting errors. By addressing each error methodically, as shown in our examples, you can often fix multiple issues with a single adjustment. It's also important to be prepared for new errors to emerge after resolving the initial ones, as some mistakes can mask others.


Keep in mind that even after successfully uploading your CSV, you may encounter issues like image upload errors. In such cases, verify the URL formatting and ensure accuracy in every detail. And, if you need to update product information, you can easily do so by re-uploading an amended CSV file. Wix's system is designed to update existing products without creating duplicates, provided the handleId's remain consistent.


This guide has walked you through various scenarios and solutions, illustrating that while errors in CSV uploads can be frustrating, they are usually fixable with a bit of patience and attention to detail. With this knowledge, you're now equipped to tackle these challenges head-on, ensuring a smoother and more efficient product upload process on your Wix store.


NX Digital Wix CSV experts

If you're still encountering errors after following the steps outlined in our guide, don't worry - help is just a click away! At NX Digital, we understand the intricacies and challenges of managing product uploads and CSV files on platforms like Wix. That's why we offer specialised CSV and product management services tailored to your needs.


Our experts are well-versed in navigating the complexities of CSV uploads, ensuring that your product data is accurately and efficiently integrated into your Wix store. We provide personalised support to troubleshoot any remaining issues you might be facing and offer solutions that are not only effective but also time-saving.


Our services are very affordable, making them accessible to businesses of all sizes. Whether you're a small startup or a large enterprise, NX Digital is committed to providing top-notch assistance without breaking the bank. By partnering with us, you can focus on what you do best – running your business – while we handle the technical details.


Don't let CSV upload errors slow you down. Contact NX Digital today, and let us help you streamline your product management process, ensuring a smooth and successful online store experience.






205 views1 comment

1件のコメント

5つ星のうち0と評価されています。
まだ評価がありません

評価を追加
Nick M
Nick M
2023年12月08日
5つ星のうち5と評価されています。

Are you having problems with CSV uploads? Ask your questions here, and include screenshots if you want some help with the errors 😀

いいね!
bottom of page