Troubleshooting CSV Product Import Issues

When importing products via CSV, several common issues can cause the import to stop, skip rows, or fail entirely. Below are the known causes and how to troubleshoot them.

Required Fields for a Product Import

A product import feed must include a SKU and Quantity. The SKU, or another product identifier used by the feed, must exist and be unique. If supplier inventory files will be used for later updates, the SKU must match the supplier's SKU; mismatched SKUs cannot be matched for inventory updates.

For products with variants, every variant row must include the required option values. For example, if the product option is Color, each variant must have a Color value, and the variant Title must not be blank. Do not leave option fields empty for variants that require them. If a product genuinely has no variants, do not map variant option columns.

CSV File Structure Issues

Missing Headers

If your CSV file does not include headers, you can still import it by mapping fields using the column index instead of column names.

• Ensure each required field is mapped correctly by selecting its index.
• This is often necessary when working with supplier files that don't define column names.

Excel Reformatting Numeric Identifiers

When editing CSV files in Excel, long numeric identifiers (such as ISBNs) may be reformatted automatically (e.g., shortened or converted to scientific notation). This can cause:

• All identifiers to become identical
• Only the first row imports successfully
• Remaining rows being ignored

To avoid this:

• Format identifier columns as Text before entering or pasting data.
• Alternatively, use a CSV-safe editor that does not auto-format numbers.

Mapping and Attribute Issues

Incorrect Variant Mapping

If variant-related fields are mapped incorrectly, the import may fail with errors such as:

• "Option value name is too long"
• "Missing combination of Product Option and Variant Option"
• "Title can't be blank" or duplicate option values

Review your mapping to ensure:

• Option names and values are taken from correct fields
• Every SKU/variant row has a nonblank variant title and required option value
• Option names are not mapped from a column that is populated only on the first row. Use a fixed option name, such as Color, when the source column does not repeat the name for every variant row.
• Only required attributes are mapped
• Variant fields use proper formatting when extracted (e.g., using split and strip)

Reviewing Import Errors

After an import, review the feed's Change Log and Recent Activity Logs. The Change Log shows the specific error and the SKU for failed products, such as a missing Product Option/Variant Option combination. It does not provide a downloadable list of all affected product names and missing fields, so search the reported SKU directly in the CSV and inspect its mapped option columns.

For errors such as duplicate option values or "Title can't be blank", check every row for the affected product. Do not leave the variant title or required option value blank; each SKU/variant row must contain the appropriate value. Correct the CSV or mapping, preview the feed, and test the import again.

Import Without Variants

If your products do not include variations, you can run the import without any variant mapping.

• Remove all variant-related fields
• Preview the import to verify correctness

Image Import Issues

Image fields may be mapped correctly but still fail to appear in previews or imports. This can be caused by:

• Incorrect image URLs
• Temporary processing issues
• Structural issues in the source file

If images are mapped correctly but do not appear:

• Re-run the preview after confirming URLs are valid
• Contact support if the issue persists, as it may require technical review

Additional Troubleshooting Cases

Import stuck at "Queuing"

The first update/import of a new feed may take longer than usual. If the feed contains more than the free test limit, additional credits may be required before processing continues.

Invalid attachment errors (Email feeds)

If you see an "invalid attachment" error when processing CSV files via email feed:

• Ensure the attachment is fully uploaded or sent
• Re-send the file if the email client delayed attachment upload
• Attach the CSV directly rather than linking it when possible

General Tips

• Always preview the feed before running a full import.
• Ensure each product has a unique identifier (SKU, barcode, etc.).
• Check that your feed updates align with your desired sync frequency.
• If uncertain, share sample SKUs to help isolate issues.

This guide consolidates common problems and steps gathered from user troubleshooting cases to help you resolve CSV import issues efficiently.

Updated on: 05/08/2026