Skip to main content
Version: Current

Troubleshooting: Import Failing (Validation Errors, Mapping Issues)

Problem​

An attempt to import data using the Settings > Imports feature fails. The import status shows Failed, or it completes but with errors reported.

Common Causes​

  1. Incorrect File Format/Encoding:
    • File is not a valid CSV or TXT format.
    • File encoding is incorrect (Zudello typically expects UTF-8, especially for CSVs). Excel sometimes saves in different encodings.
    • Delimiter issues (e.g., using semicolons instead of commas in a CSV).
  2. Header Row Issues:
    • Missing header row.
    • Duplicate column headers in the header row.
    • Special characters or excessive spaces in headers.
  3. Mapping Errors:
    • Required Zudello fields were not mapped to any column in the import file.
    • Columns were mapped to the wrong Zudello fields.
    • Incorrect mapping options selected (e.g., wrong date format).
  4. Data Validation Errors (Row Level):
    • Invalid Values: Data in a specific row/column doesn't match the expected format or type for the mapped Zudello field (e.g., text in a number field, invalid date format, value not in allowed list for a dropdown/relation).
    • Missing Related Records: Trying to link to a related record (e.g., assigning a Supplier to an Invoice via Supplier Code) where the referenced record (the Supplier) doesn't exist or is inactive in Zudello. Remember, imports generally don't create related records automatically.
    • Uniqueness Constraints: Trying to import data that violates a uniqueness rule (e.g., importing an Item with an SKU that already exists if updates aren't handled correctly).
    • Required Fields Missing: Data is missing in a column mapped to a Zudello field that is mandatory for creating/updating the record.
  5. Permissions: The user initiating the import lacks the necessary #CREATE or #UPDATE permissions for the target Module/Submodule.
  6. Large File/Timeout: Very large import files might exceed processing time limits.

Troubleshooting Steps​

  1. Check Import Status and Errors:
    • Go to Settings > Imports.
    • Find the failed import job.
    • Click the Failed status icon or a "View Errors" link (if available).
    • Review the error messages provided. They often indicate the specific row number and column/field causing the issue, along with a reason (e.g., "Invalid value for field X", "Related record Y not found").
  2. Verify File Format and Encoding:
    • Open the original import file in a text editor (like Notepad++, VS Code) or spreadsheet program.
    • Confirm it's saved as CSV (comma-separated) or TXT (tab-separated).
    • If CSV, ensure it's saved with UTF-8 encoding. In Excel, use "Save As" and select "CSV UTF-8 (Comma delimited)".
    • Check for any obvious formatting issues or unexpected characters.
  3. Check Header Row: Ensure the first row contains unique, reasonably simple headers for each column containing data.
  4. Review Field Mapping:
    • If the import failed early, you might need to restart the import process to review the mapping step.
    • Carefully check that each column header from your file is mapped to the correct Zudello field.
    • Ensure all mandatory Zudello fields (often marked with an asterisk or similar indicator during mapping) are mapped.
  5. Correct Data Validation Errors:
    • Based on the error messages from Step 1, open your import file.
    • Go to the specified row number(s).
    • Find the column corresponding to the problematic field.
    • Correct the data (e.g., fix formatting, enter a valid value, remove invalid characters).
    • Related Records: If the error relates to a missing record (like a Supplier Code not found), ensure that Supplier record exists and is active in Zudello before running the import again. You might need to import Suppliers first.
  6. Check Permissions (Admin Task): Verify the user has the necessary #IMPORT, #CREATE, and #UPDATE permissions for the target Module/Submodule.
  7. Split Large Files: If the file is very large (e.g., > 10,000 rows), try splitting it into smaller files and importing them separately.
  8. Retry Import: After correcting the file or mapping, create a new import job and upload the corrected file.

Need Help?​

If imports consistently fail and the error messages are unclear, contact Zudello support. Provide:

  • The import file you are trying to upload.
  • Screenshots of the field mapping step.
  • Any error messages received from the Imports screen.