Skip to main content
Troubleshooting and FAQs

CSV Import Errors and Invalid Leads

Fix the errors the CSV import shows, find leads that didn't arrive, and understand why leads are marked Invalid and how to mark them valid again.

Written By voiceaiwrapper

Last updated 26 days ago

This article helps you get a lead list into an outbound campaign and keep it calling. It covers the errors you can see while importing a CSV file, leads that don't show up after an import, and leads the campaign marks Invalid once it starts dialing.

Work through the sections in order: most problems are caught in the import dialog, before any lead is added.

Before you start

  • Open the campaign's Leads tab. Open your Pod (an engine or provider connection), select Campaigns, open the outbound campaign and go to Leads. The CSV import is under Add leads β†’ Add leads via csv.
  • Start from the template. In the import dialog, click Download Template to get a file with the right columns. The full walkthrough is in Import Leads from a CSV File.

The rules every file must follow:

RuleLimit
File type.csv, one file at a time
File sizeUp to 20 MB
RowsUp to 30,000 data rows, plus a header row
Required columnsCountry Code and Phone Number, as two separate columns
Country Code format1 to 4 digits, for example 1, 44, 91
Phone Number format7 to 15 digits, without the country code, spaces, dashes or brackets

The importer reads both columns as numbers, then joins them into the international format the dialer uses (+ country code, then number). For example, 44 and 7700900123 become +447700900123. Because they're read as numbers, a leading + or leading zeros are dropped: +44 and 0044 both become 44, and 07700900123 becomes 7700900123.

Errors in the import dialog

The dialog checks your file at each step. In Review data, cells with problems are tinted red; hover over a cell to read the message. Turn on Only show rows with errors to see just those rows.

A Phone Number or Country Code cell contains something other than digits, so it can't be read as a number. Common causes:

  • Spaces, dashes, dots or brackets, such as (415) 555-0123. Keep the digits only: 4155550123.
  • Letters or text, such as ext. 12 or n/a.

Click the cell to fix it in place, or fix the file and upload it again.

The Phone Number cell has fewer than 7 or more than 15 digits, or a decimal point. Check that the number is complete and that the country code isn't in this cell as well.

The Country Code cell has more than 4 digits, is 0, or has a decimal point. Enter the country's calling code only, such as 44.

On Map fields, no column is mapped to one or both required fields. Pick the right column in Map to Field for each. If your file has one combined phone column (for example +447700900123), split it into a country code column and a number column in your spreadsheet first.

The same phone number appears in more than one row of your file. A number can only be in a campaign once. Select the extra rows and click Delete Selected Rows.

Two columns are mapped to the same lead field, for example two columns set to Email. Set one of them to Custom Field or Ignore Field.

A Country Code or Phone Number cell is empty. Fill it in or delete the row.

The file has more than 30,000 data rows. Split it into several files and import them one after another. Numbers already in the campaign are skipped, so overlapping files are safe.

The file is larger than 20 MB or isn't a .csv file. Save it as CSV (not .xlsx), remove columns you don't need, or split it into smaller files.

At least one row still has an error. Edit the cells, or select those rows and click Delete Selected Rows, then click Import again. Deleting rows here doesn't change your file.

  • Greyed out: the campaign has ended. Leads can't be added to an ended campaign. Create a new campaign, or clone this one. See Clone, Edit and Delete Campaigns.
  • Missing: it's an inbound campaign. Inbound campaigns create leads from the people who call in, so they have no import.

Leads missing after an import

When you click Import, the leads are queued and added in the background. You'll see "Leads have been queued for import, please give it a few mins for the upload to complete…". If some leads are still missing after a few minutes, refresh the Leads tab and check these causes:

  1. The number was already in the campaign. Duplicates are skipped without an error. Search the Leads tab for the number.
  2. The number was saved differently than you expected. Search for the full saved number. Some file problems pass the checks but change the number:
    • The country code is also in the Phone Number cell, such as 1 and +14155550123. The + is dropped and the country code is added again, so the lead is saved as +114155550123.
    • Excel turned long numbers into scientific notation, such as 4.16E+09. This is read as a rounded number (4160000000) with no error. Format the column as text in your spreadsheet before saving as CSV.
  3. The campaign ended before the import ran. Leads aren't added to an ended campaign.

Numbers saved wrongly usually turn Invalid once the campaign tries to call them.

Why a lead is marked Invalid

A lead is marked Invalid when a call to it fails with an error. It stays in the campaign but isn't called again until you mark it valid. You'll see a red Invalid label under the lead's name and Yes - View Reason in the Invalid column. Hover over the label, or click Yes - View Reason, to see Current Error: with the error that was recorded.

The Invalid tab on the Leads tab lists all of them, and the campaign's Overview counts them under Invalid Leads.

Common errors, from most to least likely:

What the error saysWhat it meansFix
"+…" is not a phone number that can be dialled. (VAW Native)The saved number isn't a real, diallable number, usually a wrong country code or an extra leading 0.Delete the lead and add it again with the correct number.
An error from Vapi, Retell AI or another provider, such as an invalid number or a rejected destinationYour provider refused to place the call.Read the provider's message. If it's about the number, re-add the lead. If it's about your provider account (credit, permissions, rate limit), fix that first, then mark the lead valid.
Missing placeholders: … Please check the agent configuration. (ElevenLabs)The ElevenLabs agent uses dynamic variables that the lead doesn't have.Add custom fields with exactly those names (see below), or remove the variables from the agent. Then mark the lead valid.
A number cannot call itself. (VAW Native)The lead's number is the campaign's own caller number.Delete the lead.

You can't change a lead's phone number after it's added. To correct a number, delete the lead and add it again with the right number.

Deleting a lead also deletes its call logs and scheduled calls. This can't be undone.

If many leads turn invalid with the same provider error, the problem is usually the agent, number or provider account rather than the leads. Fix that first; otherwise every lead you mark valid fails again.

Mark leads valid again

Once you've fixed the cause, put the leads back in the queue:

  1. Pause the campaign. Leads can't be marked valid while it's active; you'll see Campaign Must Be Paused if you try.
  2. On the Leads tab, open the Invalid tab.
  3. Select the leads you want to retry.
  4. Click Bulk Actions, then Mark Valid. You'll see "Successfully marked N leads as valid".
  5. Resume the campaign.

Marking leads valid clears their error and sends a Leads Marked Valid event to the campaign's leads event webhook, if you've set one. See Bulk Actions on Leads and Leads Event Webhook.

Name custom fields so your agent can use them

Every column you map to Custom Field is saved on the lead, with the column header as its name. When the campaign calls the lead, the custom fields are passed to the agent as variables, together with first_name, last_name, phone_number and email.

  • Match the names your agent uses. If the prompt uses {{company}}, the column header must be company, with the same spelling and letter case.
  • Keep headers short and plain. company and appointment_date are easier to use than Company Name (from CRM).
  • Don't reuse the standard names. A custom field called first_name, last_name, phone_number or email is replaced by the lead's own value.
  • On ElevenLabs, every dynamic variable the agent uses must exist on the lead. A missing one marks the lead Invalid with "Missing placeholders".
  • On VAW Native, names that start with system. are ignored. Those names are reserved for values the platform fills in.

How variables work inside a VAW Native prompt is covered in Use Call Data and Variables in Your Prompt.