Skip to main content

Import Errors

HCSS Events Platform uses CSV file imports for bulk data entry, most commonly for importing caregivers into events. This guide covers the most common import errors, their causes, and how to fix them.

How the Import Process Works​

Before diving into specific errors, it helps to understand the import flow:

  1. You upload a CSV file on the import page.
  2. The system validates every row against the expected column schema and data rules.
  3. A preview screen shows the validation results: valid rows (ready to import) and invalid rows (with error details).
  4. You can fix errors in the CSV and re-upload, or proceed to import only the valid rows.
  5. Successfully imported rows create new records in the system.
tip

Always download the CSV template from the import page before preparing your file. The template includes the exact column headers the system expects, along with example data.

Invalid Email Format​

Error message: Invalid email format in row [N]

Cause​

The email address in the specified row does not conform to standard email formatting rules.

Common Mistakes​

ExampleProblem
jane.doe@Missing domain.
jane.doe@hospitalMissing top-level domain (e.g., .com, .org).
jane.doe@@hospital.comDouble @ sign.
jane doe@hospital.comSpace in the local part.
jane.doe@hospital .comSpace in the domain.
jane.doe@hospital,comComma instead of period in the domain.
(empty)The email field is blank.

Solution​

  1. Open your CSV file in a text editor or spreadsheet program.
  2. Navigate to the row number indicated in the error.
  3. Correct the email address to a valid format (e.g., jane.doe@hospital.com).
  4. Save and re-upload.
tip

Use your spreadsheet program's Find & Replace feature to search for common problems: double @@, trailing spaces, and commas in the domain portion.

Missing Required Fields​

Error message: Required field [FieldName] is missing in row [N]

Cause​

One or more required columns are empty for the specified row.

Required Fields for Caregiver Import​

FieldDescription
First NameThe caregiver's first name.
Last NameThe caregiver's last name.
EmailThe caregiver's email address.
SpecialtyThe clinical specialty code (must match an active specialty in reference data).

Solution​

  1. Check the indicated row for empty cells in required columns.
  2. Fill in the missing data.
  3. If you do not have the data, you cannot import the row -- either obtain the information or remove the row from the CSV.

Common Pitfall: Hidden Empty Rows​

Spreadsheet programs sometimes add invisible empty rows at the bottom of a file. The system reads these as rows with all fields missing.

Fix: Open the CSV in a text editor and delete any blank lines at the end of the file.

Duplicate Emails​

Error message: Duplicate email address in row [N]: [email] already exists

Cause​

The email address in the CSV matches an email address that already exists in the system for the current event, or the same email appears multiple times within the CSV file itself.

Two Types of Duplicates​

  1. Duplicate within the CSV -- the same email address appears in more than one row of the uploaded file.
  2. Duplicate with existing data -- the email address matches a caregiver already imported into the event.

Solution​

For duplicates within the CSV:​

  1. Sort your CSV by the email column.
  2. Look for and remove duplicate rows, keeping only one entry per email address.
  3. Re-upload.

For duplicates with existing data:​

  1. The caregiver has already been imported into this event.
  2. If you need to update their information, use the Edit function on the caregiver detail page instead of re-importing.
  3. If you want to import the row anyway (e.g., different event), verify you are importing into the correct event.
info

The system uses email address as the unique identifier for caregivers within an event. One caregiver can exist in multiple events but cannot appear twice in the same event.

Invalid Date Format​

Error message: Invalid date format in row [N], column [ColumnName]. Expected MM/DD/YYYY.

Cause​

A date field contains a value that does not match the expected format.

Expected Format​

The platform expects dates in MM/DD/YYYY format:

CorrectIncorrect
01/15/20261/15/2026 (missing leading zero -- may work, but use two digits for reliability)
12/31/202631/12/2026 (DD/MM/YYYY -- European format)
03/05/20262026-03-05 (ISO 8601 -- not supported in CSV import)
06/15/2026June 15, 2026 (text date -- not supported)
09/01/20269/1/26 (two-digit year -- ambiguous)

Solution​

  1. Open the CSV and locate the row and column indicated in the error.
  2. Reformat the date to MM/DD/YYYY.
  3. For bulk reformatting, use a spreadsheet formula or find-and-replace.

Spreadsheet Auto-Formatting Warning​

Spreadsheet programs (Excel, Google Sheets) often auto-format dates into their own locale format when you open a CSV. This can silently change 01/15/2026 to 15-Jan-2026 or 2026-01-15.

To prevent this:

  1. In Excel: Open the CSV using the "Import from Text/CSV" wizard. Set the date columns to "Text" format before importing.
  2. In Google Sheets: Format the date columns as "Plain text" before editing.
  3. Best practice: Edit CSV files in a plain text editor (Notepad, VS Code, Notepad++) when possible.

File Encoding Issues​

Error message: Unable to parse file. Please ensure the file is UTF-8 encoded. or garbled/corrupted data in the preview.

Cause​

The CSV file is saved with an encoding that the system cannot interpret correctly. This commonly occurs with files created on different operating systems or exported from legacy software.

Supported Encoding​

The platform expects UTF-8 encoding. Files in other encodings (e.g., Windows-1252, ISO-8859-1, UTF-16) may cause parsing failures or display garbled characters for accented names and special characters.

Solution​

Option 1: Re-save as UTF-8 in a text editor​

  1. Open the CSV in a text editor (Notepad, VS Code, Notepad++, Sublime Text).
  2. Use Save As or File > Encoding > UTF-8.
  3. In Notepad++: Go to Encoding > Convert to UTF-8 > Save.
  4. In VS Code: Click the encoding name in the bottom status bar > Save with Encoding > UTF-8.

Option 2: Re-export from the source​

If the CSV was exported from another system (e.g., an HRIS or staffing platform), look for an encoding option in the export settings and select UTF-8.

Option 3: Re-save from Excel​

  1. Open the file in Excel.
  2. Go to File > Save As.
  3. Select CSV UTF-8 (Comma delimited) (*.csv) as the file type.
  4. Save and re-upload.
note

The UTF-8 with BOM (Byte Order Mark) variant is also supported. If your editor offers "UTF-8 with BOM" as an option, that will work fine.

Large File Handling​

Error message: File size exceeds the maximum limit of [X] MB or the import appears to hang/time out.

File Size Limits​

LimitValue
Maximum file size10 MB
Maximum rows per file10,000

Symptoms of Large File Issues​

  • The upload progress bar stalls.
  • The browser tab becomes unresponsive.
  • The server returns a timeout error.

Solution​

Split the file into smaller batches​

  1. Open the CSV in a spreadsheet program.
  2. Copy the header row.
  3. Split the data rows into files of 5,000 rows or fewer (each file must include the header row).
  4. Save each batch as a separate CSV file.
  5. Import each batch one at a time.

Remove unnecessary columns​

If your source file contains extra columns beyond what the platform requires, remove them before uploading. Fewer columns mean a smaller file size.

Compress data​

Remove any blank rows, trailing whitespace, and unnecessary formatting. This can reduce file size significantly for large files.

tip

If you regularly import more than 10,000 records, contact your administrator about bulk import options or API-based integrations.

Error Summary Table​

ErrorCauseQuick Fix
Invalid email formatEmail does not match name@domain.tld pattern.Correct the email address.
Missing required fieldA required column is empty.Fill in the missing data.
Duplicate emailEmail already exists in the event or CSV.Remove the duplicate row or edit the existing record.
Invalid date formatDate is not in MM/DD/YYYY format.Reformat to MM/DD/YYYY.
Encoding errorFile is not UTF-8 encoded.Re-save the file as UTF-8.
File too largeFile exceeds 10 MB or 10,000 rows.Split into smaller batches.

Preventive Measures​

  1. Always use the template -- download the CSV template from the import page and use it as your starting point.
  2. Validate before uploading -- spot-check your CSV in a text editor before uploading. Look for obvious problems like empty rows, misaligned columns, and encoding issues.
  3. Test with a small batch first -- before importing a large file, try importing just 5-10 rows to verify that your formatting is correct.
  4. Keep a clean source -- maintain a master spreadsheet with consistent formatting and validated data. Export from this master rather than editing CSV files directly.
  5. Document your process -- create a step-by-step checklist for preparing import files. This is especially valuable when multiple team members handle imports.

Still Having Issues?​

If you encounter an error not covered here, or if the solutions above do not resolve your problem:

  1. Take a screenshot of the error message and the preview screen.
  2. Save the problematic CSV file.
  3. Contact your administrator or see Getting Help for support options.