Agiled Docs

Import failures usually come from source file quality, missing required fields, or mismatched column mapping.

Prepare the CSV

Use one row per record, clear column headers, consistent date formats, required fields, and matching names for related records such as accounts or projects.

Before uploading, remove blank rows, merged spreadsheet headers, notes above the header row, formulas that have not been pasted as values, and columns that do not belong in Agiled.

Save a clean copy of the CSV you actually upload. If the import fails, this file is the source of truth for troubleshooting.

Keep the original export unchanged and work from a cleaned copy. If cleanup goes wrong, you can compare the failed rows against the untouched source instead of guessing what changed.

Mapping Looks Wrong

Update the mapping before committing the import. Rename unclear CSV headers and upload again when needed.

If a column maps to the wrong field, stop before importing. Fix the CSV headers or mapping first. It is faster to correct the file than to clean up hundreds of records after a bad import.

Rows Fail Validation

Review failed rows for missing required values, invalid emails, invalid dates or numbers, unknown related records, duplicates, or values that do not match allowed status and priority options.

Fix the CSV and rerun only the corrected rows.

Keep the failed-row file separate from the original source export. This makes it clear which rows still need action and prevents reimporting successful rows.

Add an import tag, batch name, or temporary marker when the import flow supports it. That makes it easier to find and review records created by the retry.

Duplicates usually come from inconsistent names, multiple email addresses, or records that already exist in Agiled. Related-record failures happen when a row references an account, project, pipeline, stage, user, category, or status that Agiled cannot match.

Create or import related records first, then rerun the dependent import.

When duplicates are possible, import a small sample and search for those records before importing the full file. Check the matching fields Agiled used, such as email, name, external ID, or related account.

Fix Setup Before Retrying

If many rows fail for the same missing value, fix workspace setup first. Create missing users, accounts, pipeline stages, product categories, custom attributes, or statuses before retrying the CSV.

Safe Retry Process

Download or copy the failed rows.
Fix only those rows.
Remove rows that already imported successfully.
Run a small test import.
Review the created records before importing the rest.

Name the retry file clearly, such as contacts-failed-rows-fixed-2026-05-18.csv, so teammates do not accidentally reimport the original failed file.

After the retry, spot-check records from both the original successful import and the retry file. This confirms the final dataset is consistent instead of only proving that failed rows now save.

When To Stop

Stop importing and inspect settings when many rows fail for the same reason. Common setup gaps include missing custom attributes, missing pipeline stages, missing users, missing product categories, or related records that should have been imported first.

Do not repeatedly retry the same file without changing the cause. Repeated imports can create duplicates and make cleanup harder.

Evidence To Collect

Before asking for help, collect the import type, CSV header row, failed-row examples, mapping choices, error messages, and whether related records already exist. This usually reveals whether the fix belongs in the CSV or workspace settings.

Import Failures