Fixing CSV upload errors¶
In short: Most CSV upload problems come down to the file not matching the CSV File Type you chose, or to dates, amounts or unmatched donors. Check that the receipt method's CSV File Type matches the exact bank/export that produced the file, then work through the specific messages below.
Overview¶
When a bank-statement or payment-export upload does not work, it is almost always because the file's layout does not match the CSV format you selected, or because of dates, amounts or unmatched donors. This article lists the errors you may see in the CSV Receipt Uploader and how to fix each one.
Before you start¶
- Know which bank account or provider produced the file, and which built-in format matches it. See Supported bank and CSV file formats.
- Make sure a receipt method with the correct CSV File Type exists and is Active. See Setting up CSV receipt upload (the CSV receipt method).
Common issues & solutions¶
| What you see | What it means | How to fix it |
|---|---|---|
| "Link a CSV template" with "Please set up a csv type on a receipt method then return to this page." | No active receipt method has a CSV File Type attached, so the uploader has nothing to offer in the Method dropdown. | Click Setup CSV Type (or go to Settings → Receipts → Receipt Methods), add or edit a method, set its CSV File Type to the format matching your file, tick Active, save, and return to the uploader. |
| "Error: … Please check your CSV file type and receipt method then try again." | No transactions could be read — the format attached to the chosen method doesn't match the file's columns, or every transaction is outside the date window the uploader reads. | Confirm the Method matches the exact bank account and export type that produced the file; check the file holds incoming (credit) transactions; or rearrange your data into the Generic layout. Click Retry to start over. |
| "Transaction date is older than 5 years and cannot be receipted." (row marked ERROR) | You ticked a transaction dated more than 5 years ago. | Leave those rows unticked. Only receipt transactions dated within the last 5 years. |
| My deposits show under Debit Transactions and are Excluded. | The amounts are being read as negative — usually the file is read with the wrong format and the amount column is mismatched. | Re-check the CSV File Type against the file source. If correct and the problem persists, try the Generic layout or ⚡ SmartDetect. |
| ":attribute is required" (e.g. Donor, Project or Receipt Type is required). | You ticked a transaction to save without completing the required fields in its expanded row. | Expand the row, choose a Donor, a Project and a Receipt Type, then click Issue Receipts again. Use Add Donor at the top of the uploader if the donor doesn't exist yet. |
| The donor wasn't matched automatically (left blank). | ActiveDonor matches donors from the file's reference using email, a SA cellphone number (10 digits starting with 0), a donor reference, or a previously-used payment reference; none was present or recognised. | Choose the donor by hand in the expanded row before saving. Store the donor's email, cellphone or reference on their record so future uploads match. |
| Rows marked DUPLICATE. | Those transactions were already receipted in an earlier upload. | Nothing to do — duplicate rows link to the existing receipt and won't be receipted again. This is the safeguard against double-receipting overlapping statements. |
| "Cannot identify clear transaction pattern" (after using ⚡ SmartDetect). | The AI could not work out which columns are the date, amount, description and reference. | Fall back to a built-in CSV File Type, or rearrange the file into the Generic layout. |
| "SmartDetect analysis timed out. Please try again or use manual CSV rules instead." | The AI analysis took too long. | Try again, or use a built-in CSV File Type instead. |
| "Network error during SmartDetect analysis. Please check your internet connection and try again." | The AI service couldn't be reached. | Check your connection and retry, or use a built-in CSV File Type. |
Why the format must match the file¶
Each CSV File Type reads fixed column positions for one specific bank or provider and export type. If you pick the wrong one — for example a business format for a savings-account export, or one bank's format for another bank's file — the uploader reads the wrong columns and either reports that nothing could be read, or pulls in wrong amounts and dates (often showing your deposits as Debit Transactions). Always match the CSV File Type to the exact account and export that produced the file. See Supported bank and CSV file formats.
Still stuck?¶
- Save the file again from your bank/Excel as CSV (Comma delimited) and retry. See Exporting from Xero for CSV upload for the save-as guidance, which applies to any spreadsheet.
- Click Retry or Reset in the uploader to clear the current file and start fresh.
- Check the upload history on the Batch Uploads page to see what imported versus was skipped. See Reviewing CSV upload history.
FAQ¶
The uploader says it couldn't read any transactions — why? Either the file doesn't match the CSV File Type on the method you chose, or every row is outside the supported date range — see My CSV upload didn't work — how do I fix it? for the three usual causes and the fix.
Why is my old donation showing an ERROR when I try to save it? Transactions older than 5 years can't be receipted. You'll see "Transaction date is older than 5 years and cannot be receipted." — leave those rows unticked.
Why did the donor not fill in automatically? The reference in your file didn't match an email, a SA cellphone number, a donor reference, or a previously-used payment reference. Pick the donor by hand, and add the matching detail to the donor record for next time.
Why are some rows marked DUPLICATE? They were already receipted in an earlier upload. It's not an error — they won't be receipted twice.
SmartDetect failed — what now? Fall back to a built-in CSV File Type, or rearrange your file into the Generic four-column layout (Date, Description, Reference, Amount).
Related¶
- My CSV upload didn't work — how do I fix it?
- Uploading receipts via CSV
- Supported bank and CSV file formats
- Setting up CSV receipt upload (the CSV receipt method)
- Exporting from Xero for CSV upload
- Reviewing CSV upload history