Troubleshoot and recover failed CSV imports
Start with the Job status, its first error and the affected chunk's results. Determine whether the problem is an ordinary row failure or a fatal failure of a processing transaction before rerunning any data.
Resolve ordinary row errors
Mapping, conversion and ordinary Salesforce DML errors are reported as row outcomes. Valid records can commit and later chunks can continue, so the Job may finish as Completed with failed rows.
Download the affected chunk's results. Review each failed row's complete outcomes, including successful records created by other Targets. Correct the data or mapping, then prepare a deliberate correction run using identifiers that avoid duplicate records.
A failed row does not imply that every Action for that row rolled back.
Example: a completed import with a failed row
The demonstration file contains three Account rows, with the Name missing from the second row. With Rows per chunk set to 2 and Batchable selected, the first batch creates the Dublin Account and reports REQUIRED_FIELD_MISSING for the Cork row. The second batch still creates the Galway Account.
The parent Job finishes as Completed, while Create Sample Accounts shows Completed with errors: two succeeded and one failed. The results CSV identifies the failed source row as __payloads_row = 2 and explains Required fields are missing: [Name].
Review Target outcomes and each batch download; Completed alone does not mean every row succeeded.
Prepare a correction file containing only the Cork row with its Name supplied. Do not include the two successful Insert rows again. The correction is a new invocation; the original Job and its result files remain the record of the first attempt. In the verified correction run, one Account was created and an independent record check confirmed that the original two successful Accounts were not duplicated.
Diagnose a fatal failure
Parsing and structural errors, Action execution exceptions and fatal Target failures can stop processing and roll back the current chunk. Previously committed chunks remain intact.
For file-read failures, check the pinned file version, access for the runtime user and connection principal, Named Credential authentication and allowed package namespace. File range reads must work; successful Job creation alone does not validate the file's contents or later reads.
For limit failures, examine the Actions performed per chunk and reduce Rows per chunk before a new run. Large or wide rows, nested arrays and Salesforce automation can make a small-looking CSV expensive to process.
Check the Job's preserved checkpoint and the last committed chunk. Do not assume the whole file is unprocessed because the final Job status is Failed.
Example: parsing stops after an earlier chunk committed
A separate three-row file contains two valid Accounts followed by an unterminated quoted value. With Rows per chunk set to 2, the first chunk commits its row outcomes. The next chunk fails with The CSV ends inside a quoted value.
In this example, the Job preserves two processed rows and a byte offset of 84 out of 103 bytes. It reports that source rows could not be recovered, and the failed batch shows No source rows captured. Earlier chunks are not rolled back: inspect their row outcomes to establish which records were written. The failing batch's results cannot reconstruct a row that the CSV parser could not read.
Use the Job error, checkpoint and earlier batch outcomes together when deciding what to correct.
Understand interrupted-job reconciliation
Imports maintain the recurring Payloads CSV job reconciliation schedule. It checks hourly for interrupted work, while Job detail refresh can also reconcile the visible Job.
Active queued or processing native executions are left alone. Terminal or missing executions receive a five-minute grace period before reconciliation can mark an interrupted parent Failed. Detection also depends on the schedule and Salesforce queue availability; it is not a five-minute completion guarantee.
Keep the recurring schedule enabled. Check Apex Jobs and the Job's async reference if work appears stuck, including failures while scheduling a continuation.
Reconciliation updates status and error information. It does not advance the checkpoint, rerun Targets or resume the import.
Plan a correction run
CSV Replay is disabled in this release. There is no general resume button or automatic row retry.
Retain the original file and results, establish which records committed, then choose the rows to process again. Use appropriate update or upsert identifiers where possible. A fresh invocation is new work, so an Insert Target can create duplicates if successful rows are included again.
Do not edit the Payload while another import is active because later chunks reread its configuration. If source cleanup was selected, completion with row errors may already have deleted the original File. Failed imports retain it, and result-file retention is separate. A newer version of the source File prevents cleanup; a deletion error is recorded on the completed Job. Check the actual File before relying on it being present or deleted.


