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: [email protected]
• Include all information above
• Attach error report and sample CSV