How to Fix a Failed Bulk Import

Use this guide when a bulk import finished with failed rows, or when validation blocked the file before any records were created. Failed rows are never imported. Successful rows are committed and stay in DualEntry. Your goal is to fix the failed rows and import those rows only. To look up a specific error message, see Bulk Import Errors.

​

Before you start

• The source file you uploaded, in its original format.
• A role that can run bulk imports. Admin, Controller, and Accountant hold that permission; other roles can view past imports but not start one.
• Access to the records your file references, such as GL accounts, vendors, customers, items, and companies.
• Spreadsheet software that can save CSV. Excel and Google Sheets both work, with the caveats in Step 4.

​

Step 1: Open the import and read the result

1. Go to Workflows and choose Bulk Imports.
2. Open the import you want to fix.
3. Note four things: the record type, whether it ran as a create or an update, how many rows succeeded, and how many failed.

The status screen lists the failed rows in a table with Row #, Field, and Reason columns. That table is often enough to spot the pattern without downloading anything. If nothing was attempted, the file never passed validation. Skip to Step 6.

​

Step 2: Get the error report

Download the report for the stage that failed. Validation produces <record type>_validation_report.csv; a completed import produces <record type>_import_report.csv. Both contain failed rows only, with three columns:

• row_index, the source row number, counted from the header row so the first data row is one higher.
• error_field, the column that caused the failure.
• error, the message.

Keep the report open next to your source file. The row numbers line up with your original file, not with the filtered report.

​

Step 3: Group the errors before you fix anything

Sort or filter the report by the error column. Most failed imports come down to two or three distinct causes repeated across many rows. A file with 130 failures usually has one bad date format and one missing vendor, not 130 separate problems. For each distinct message, find the cause and fix in Bulk Import Errors, then apply the fix to every affected row at once. Only the first 100 issues are reported per file, so on a large file treat the report as a sample of the problems rather than a complete list.

​

Step 4: Fix the values

Correct the values in your source file, not in the error report. The report is a record of what failed, not an import file.

​

Values rejected as invalid

A value fails when it does not match the type the destination field expects. Spreadsheet software causes most of these by rewriting values on save. After editing in Excel, save as CSV UTF-8 (Comma delimited). Reopening a CSV in Excel re-applies the same conversions, so make Text formatting the last thing you do before saving.

​

Values that reference a record

referenced value "..." not found. means the row points at a record DualEntry cannot resolve. Check, in this order:

1. The record exists. Search for it in DualEntry.
2. The record belongs to the company on the row.
3. The value matches exactly, with no trailing spaces and no dropped leading zeros.

An archived record produces a different message, referenced value "..." is inactive., so if you see that one the record exists and only needs reactivating. Create or reactivate the referenced record first, then re-import. Imports do not create records on the fly for referenced fields.

​

Rows that match more than one existing record

Bulk Import upserts. It creates rows that do not exist and updates rows that match an existing record on the record type’s match key. Multiple existing records match this row's ... means two or more existing records share the same key values, so the import cannot choose one. Resolve it one of these ways:

• Correct the row if the key values are wrong, for example a mistyped date or vendor.
• Archive or merge the duplicate records that already exist in DualEntry.
• Add the record type’s identity column to your file and supply the ID of the record you mean. An identity value overrides the composite match and targets exactly one record.
• Split the file and import the affected records individually.

Re-uploading the same file without changing the data reproduces the same error every time.

​

Multi-row records

Bills, invoices, journal entries, and other line-level record types are imported as multi-row records. Rows are grouped into one record by the columns that identify the header, then validated as a group. Because of the grouping, one bad line can fail the whole record, and key columns must repeat on every line of the record. Keep the header columns identical across all lines of a record. Do not leave them blank on continuation lines. Errors on these record types name the line, as in Line 3, column "Amount" — value is invalid.

​

Step 5: Re-import the failed rows only

1. Copy the corrected failed rows into a new file with the same header row as the original.
2. Go to Workflows > Bulk Imports > New Import and select the same record type.
3. Choose the same method the original import used, Create or Update.
4. Upload the new file.
5. Confirm the column mapping. Mapping is not carried over from the earlier import, though a saved mapping template can be reapplied from the Templates menu.
6. Review the validation summary. Every row should be valid before you continue.
7. Confirm the import.

​

Step 6: When the whole file fails validation

If no columns mapped, or the wizard reports that none of your rows are valid, the problem is the file’s shape rather than its values. Check the file:

1. Row 1 is the header row. No title rows, no logo rows, no blank rows above the header.
2. One header row only. Merged or stacked headers do not parse.
3. Every column has a header. A blank header stops the file.
4. No merged cells anywhere in the data.
5. One record type per file.
6. For XLSX, the correct sheet is selected. Bulk Import reads the first sheet by default.
7. No totals row at the bottom.

Then start from the official template:

1. In the import wizard, select the record type and choose Download template. When the wizard offers a method, the button reads Download import template or Download update template to match it.
2. Paste your data under the template’s headers, column by column.
3. Upload the template file.

The template carries the exact column names for the record type, so columns map automatically and you can see which fields are required before you upload. Note that the file template and the Templates menu are different things. The file template is a spreadsheet with the right headers; a mapping template is a saved set of column mappings you can reapply to a future import of the same shape.

​

Fix with Copilot

Some organizations see Copilot entry points on the bulk import screen. On a failed import, Fix with Copilot hands the error report and your original file to Copilot, which groups the failures by root cause and returns a corrected file containing only the failed rows. Before an upload, Check and enrich with Copilot reviews a file against the record type’s template and flags what would fail. The pre-upload check covers accounts and journal entries. If you do not see these buttons, they are not enabled for your organization, and the manual route in this guide is the way through.

​

Step 7: Verify the result

1. Confirm the import reports every row as successful.
2. Open the success screen’s link to the imported records, which filters to that import batch.
3. Spot-check two or three records against the source file, including one record that had failed the first time.
4. For transaction imports, confirm the totals against your source system before you rely on the data.

​

If the same error comes back

• Confirm you uploaded the corrected file. Excel keeps the original open under the same name.
• Confirm the row numbers in the new report point at rows you actually changed. Row numbers count from the header row, so the first data row is one higher.
• Re-check the value in the raw file rather than in the spreadsheet view. Open the CSV in a text editor to see what was written to disk.
• If the value looks correct in the text editor and still fails, look up the message in Bulk Import Errors for causes that are not visible in the cell, such as an inactive referenced record or a locked period.

​

Related

• Bulk Import: Load Records from a File
• Bulk Import Errors: Reference
• How to Configure the Chart of Accounts
• How to Lock and Unlock Accounting Periods
• Retry, Resync, and Archive: Managing Integration Syncs