Problem #

You may see Client import failed errors while attempting to perform an import using ImportAssist:

Client import failed: The system found an existing client with email address \'{email}\' (Client ID {existingId}).

Cause #

The message that follows Client import failed indicates the error’s cause. Typically, failures are due to a problem with the file or the data that it contains.

Solution #

Check the error message to determine the correct solution:

Incorrect Filename #

If you see one of the following error messages, the problem is due to an invalid filename. Import filenames must end with .client.csv.

The filename 'example.csv' does not match the expected format: <name>.<template>.csv

The template type 'customers' in file 'example.customers.csv' is not supported.` | The import file's name is invalid. Import filenames **must** end with `.client.csv`.

Solution #

Update the filename to ensure that it ends with .client.csv.

Invalid File Format #

If you see the following error message, the file’s first row does not contain the correct header information for each field.

The CSV file header was unreadable or is empty.

Solution #

Make certain that the file uses the correct import file format.

Existing Clients #

If you see the following error message, a row in the import file duplicates data that already exists in WHMCS:

The system found an existing client with email address \'{email}\' (Client ID {existingId}).

If an identical UUID or email address already appears for an existing client in your WHMCS installation, the system will not import the new client.

Solution #

To resolve this issue, see Missing Imported Clients.

Last modified: 2025 December 16