How To Troubleshoot List Imports

read
Last updated at:

Overview

When uploading subscribers to a new or existing list in Klaviyo, your list may fail to upload. If this occurs, you will see that a certain number of records were skipped. Often, this is the result of a small error. In this article, you will learn common troubleshooting tips to overcome this roadblock and upload your list successfully.

Checklist

Want to make sure your file will import? Check the list below before importing your list.

  • CSV File (not any other format)
  • File size is 50 MB or less
  • First row is headers
  • Every row has an email address associated with it
  • No duplicate email addresses
  • All email addresses are formatted properly

Our Support Team is not able to import CSVs into Klaviyo on your behalf. If you need help with an import, please check out the troubleshooting section below for tips and tricks on how to successfully troubleshoot list import issues.

Having trouble uploading a list of profiles with SMS consent? Check out Klaviyo’s Guide to Uploading a List of SMS Contacts

Import Delay

If you import a large file with a significant amount of data, the import process may take several hours to complete. Unfortunately, there is no way to speed up this process once it has begun. However, one way to preemptively expedite the import process is to remove all duplicate emails from your CSV before importing. We highly recommend planning to import a new list at least one day in advance of when you intend to email the list.

After an import begins, you will initially see a status bar. If you click away, you will otherwise be able to track the import’s progress by watching the list count increase over time. We will send you an email as soon as a list import completes.

Import Troubleshooting

If your list fails to upload, look for the following common errors in your CSV file that may be causing this roadblock:

All Columns Imported as a Single Field 

If you are using a version of Excel that does not use English as the default language, your software may use semicolons and not commas as the separator in your file. If this is the case, your file may look like this upon import:

Semicolon_error.png

To remedy this, head to your computer's Language & Regional Settings > Advanced Settings > List (or Number) Separator. Replace the semicolon with a comma and save. Now when you export files as a CSV, they will use the comma format. Note that the exact location of this setting may differ across operating systems.

2017-05-22_14-59-31.png

Also, check to make sure that your CSV aligns with Klaviyo’s formatting requirements. If you have not already, head to our documentation on formatting your data. For example, one of the required fields is for email addresses. This must be the first field listed in your upload with a title containing either "Email" or "Email Address."

Incorrect Date or Timestamp Formatting

You may be using the wrong format for dates or timestamps. If you have included either and are unsure of Klaviyo’s accepted formats, head to Acceptable Date and Timestamp Formats for Profile and Event Properties.

Mismatched Data Types

When you import a list into Klaviyo, you will arrive at a field mapping page. Here, you will match any properties to their corresponding data type in Klaviyo. For example, Email should have a String data type; whereas, if you upload a custom property for Birthday, you will want to set the data type to Date.

new_data_types.png

Review the data types and acceptable formats in the chart below. 

Data Type

Accepted Formats

Example data

String

Any text, or combination of text and numbers. If you are unsure what format your data is in, choose this option. 

email@example.com

Hello, world

$5.00

Numeric

All numbers. Do not include currency symbols in numeric fields. 

2

5.0031

130.0

Boolean

True or false values.

true

false

Date

Reference our guide to Acceptable Date and Timestamp Formats for Profile and Event Properties to learn about accepted date formats.

2014-09-01 13:34:08

List

Data must be formatted as a JSON array. 

["apples","bananas","oranges"]

["apples"]

Consent

Data must be formatted as a JSON array of marketing channels the subscriber has consented to. Channel options are limited to email, web, sms, directmail, mobile, and push. 

["email"]

["sms","push","directmail"]



For more information about what the different data types entail and which to select when importing your list, head to About Data Types.

Duplicate Headings or Required Values

Check for duplicate headings or column headings with blank values. If you have multiple blank columns, delete all blank columns to the right of those with values. Otherwise, open the file in a plaintext editor and delete any extra commas that have no values in between them.

For required values (e.g., email addresses) you cannot have duplicates. Before you import a file, you can check for duplicate email address entries in Microsoft Excel by clicking Data > Remove Duplicates.

2017-05-22_15-02-32.png

If you have exported a list in order to add those profiles to another list in the same Klaviyo account, you only need to upload the email address column. Uploading other fields can result in data being overwritten, or the upload failing altogether.

Don’t worry: the custom profile properties will still exist in your Klaviyo account. Because profile properties are stored within profiles, you can add or remove profiles from lists without impacting their profile data.

Missing Value in a Required Field

Check that all required fields have values associated with them. For example, if one of your contacts listed is missing an email address under the email column, you will see an error when uploading. Check to make sure that each contact you wish to upload has a value for all required fields. If they are empty, fill them in prior to your next attempt to upload. 

Invalid Email Formatting

Klaviyo will automatically skip email address entries that are not in a valid format. A valid email address, such as jane@example.com, is made up of a local part (jane), an @ symbol, and a case-insensitive domain part (example.com). If any of these required parts are missing, we consider the email invalid. If there are erroneous spaces in the email address, we will also consider the email invalid.

You can search your CSV for invalid emails. Highlight the list of email addresses and select Data > Filter. Then, filter out any email addresses that do not contain symbols like "@" or "." Fix or remove these invalid emails before re-attempting your import.

If your email addresses are all formatted correctly, but you still receive this error message, check for any line breaks within cells and remove them. Line breaks within a cell in your CSV will be interpreted as new rows in the upload, causing misalignment between the data and your headings.

Selected File Contains Empty Columns

If your CSV contains additional columns above the header row, you may receive the error message “The selected file contains empty columns. Please remove the empty columns and try again.”

Extra_header_row_error.png

If you receive this error message, remove any extra rows at the beginning of your file before retrying the upload. As a reminder, the first row of your file must contain headers for each column.

Additional Resources

x
Was this article helpful?
66 out of 251 found this helpful