---
updatedAt: 2026-02-24T13:50:46.000Z
agentTools:
  projectIndex: https://help.zluri.com/llms.txt
---

# Troubleshooting

## Common Errors and Solutions

### Error: “File must be uploaded before accessing mapping structure”

**Cause:** Trying to map fields before file upload completes

**Solution:**
Wait for upload to show green checkmark

***

### Error: “Entity config not found. Please upload a sample file.”

**Cause:** No sample file uploaded for this data type

**Solution:**

1. Go back to the upload step
2. Upload a sample CSV file
3. Wait for upload to complete
4. Continue to mapping

***

### Error: “Unable to read the uploaded file”

**Cause:** File is corrupted, wrong format, or encoding issue

**Solution:**

1. Verify file is CSV format (.csv extension)
2. Open file in text editor to check it’s readable
3. Save file as CSV
4. Try uploading again

***

### Error: “Field \[name] is required”

**Cause:** Required field is empty in your CSV

**Solution:**

1. Download error report to see which rows
2. Add values for the required field
3. Re-upload corrected file

***

### Error: “Invalid \[type] value for field \[name]”

**Cause:** Data doesn’t match expected type

**Examples:**

* Text in a number field: “ABC” in Employee ID
* Invalid date format: “01/15/2024” instead of “2024-01-15”
* Invalid boolean: “maybe” instead of “true” or “false”

**Solution:**

1. Check error report for specific rows
2. Fix data to match expected format
3. Re-upload corrected file

***

### Error: “Mapping not configured for \[entity]”

**Cause:** Field mappings not saved for this data type

**Solution:**

1. Go to the mapping step for this data type
2. Map all required fields
3. Click “Save Mappings”
4. Try validation again

***

### Validation Takes Too Long

**Cause:** Large file or system load

**Expected Time:**

* Small files (< 1000 rows): a few seconds
* Medium files (1000-10000 rows): less than a minute
* Large files (> 10000 rows): around a minute

**Solution:**

1. Wait for validation to complete
2. Don’t refresh the page
3. If stuck for > 10 minutes, contact support.

***

### Upload Fails or Times Out

**Cause:** File too large or network issues

**Solution:**

1. Check your internet connection
2. Try uploading a smaller file
3. Split large files into multiple smaller files
4. Contact support if issue persists

***

### Error Report Shows Many Errors

**Cause:** Data quality issues or mapping problems

**Solution:**

1. Download error report
2. Look for patterns in errors:
   1. Same field failing? Check mapping
   2. Same error type? Fix data format
   3. Random errors? Check data quality
3. Fix issues in batches
4. Re-upload and validate

***

## Getting Help

**Before Contacting Support:**

Gather this information:

* Connector name
* Data type (Users, Groups, etc.)
* Error message (exact text or screenshot)
* Error report (if available)
* Sample of your CSV file (remove sensitive data)

**Contact Support:**

* Email: <support@zluri.com>
* Include all information above
* Attach error report and sample CSV