Overview
This article covers diagnostic and resolution steps for malformed-syntax errors and parsing failures during bank statement imports in ZoneReconcile. It applies to all import methods: manual imports (Single/Multi-Import and Instant Upload) and automated background imports (SFTP and File Cabinet auto-import scripts).
Step 1: Identify the error source
Before troubleshooting by file format, identify where the error appears based on your import method:
- UI banner error — the error appears immediately after you upload the file
- Bank Statement Auto Import / Bank Statement to Process record — review the Error field on the custom record list
-
Script execution logs — review the NetSuite Script Execution Logs for the relevant scripts, such as
ZR Auto Import BSTP MR
Step 2: Inspect the source file
Download and open the original bank statement file in a text editor or appropriate inspection tool. Verify the file does not contain unexpected characters, formatting issues, corrupted content, or structural inconsistencies before proceeding to format-specific troubleshooting below.
CSV, delimiter, and custom text format errors
CSV and delimited text imports require the Bank Account Configuration to match the structure and formatting of the uploaded file exactly. The table below covers the most common root causes and their resolutions.
| Root cause / symptom | Common error indicator | Resolution |
|---|---|---|
| Delimiter mismatch | Column alignment errors, Invalid number, or Date parsing failed | Verify Bank Account Configuration > Delimiter. Ensure the configured delimiter matches the file's delimiter, such as semicolon (;), tab (\t), or pipe (|). |
| Header row misconfiguration | First line fails to parse, or header text is read as an amount or date | Verify the Has Header Row setting. If enabled, ZoneReconcile skips the first row. Disable this setting if your CSV has no header row. |
| Decimal or digit separator issues | Amounts are incorrectly scaled or fail numeric validation | Verify the applicable currency and number-format settings. European number formats such as 1.234,56 require the appropriate decimal and digit separator configuration. |
| Unescaped quotes or additional commas | Unexpected column shifts or truncated fields | Ensure transaction descriptions containing commas or quotation marks are properly enclosed using double quotes. |
| Blank trailing lines | Empty-line or end-of-file errors | Remove unnecessary blank rows or trailing lines from the CSV file before uploading. |
Important: If you are using a Multiple Configuration record for CSV, set header rows only on the Multiple Configuration record. The header/footer row fields in the specific Bank Account Configuration must be left empty.
MT940 parsing errors
MT940 files use structured SWIFT message formats. Parsing failures occur when a bank-generated file contains non-standard data, invalid tag structures, or unexpected characters.
Trailing non-standard characters
You attempt to import an MT940 file and see the following error:
MT940_PARSING_ERROR: parseTag62F: unable to parse closingBalance value in current line
The bank or banking portal may have appended additional metadata, HTML/XML content, or unexpected characters after the closing balance tag. To resolve:
- Open the original MT940 file in a text editor.
- Navigate to the final balance tag, such as
:62F:or:64:. - Verify that no unexpected characters or additional content appear after the closing balance value.
- Remove any invalid trailing content.
- Save the file and retry the import.
Missing mandatory SWIFT tags
An unhandled exception occurs during MT940 processing. Verify that the following required SWIFT tags are present and correctly structured:
-
:20:— Transaction Reference Number -
:25:— Account Identification / IBAN -
:28C:— Statement Number / Sequence -
:60F:— Opening Balance -
:61:— Statement Line / Transaction Details -
:62F:— Closing Balance
Ensure all required tags are present, correctly formatted, and appear in the expected sequence.
💡 Tip: If certain :61: lines are missing from the imported statement, check the Counterparty Mandatory (MT940) preference in the related Bank Account Configuration. When enabled, ZoneReconcile ignores all :61: lines that do not have a corresponding :86: tag.
CAMT.053 / XML parsing errors
CAMT.053 and CAMT.054 files use the ISO 20022 XML format. Parsing failures may result from malformed XML, invalid character encoding, unsupported characters, or missing required elements.
Unescaped XML special characters
You see an error such as:
XML_PARSING_ERROR: EntityRef: expecting ';' or unclosed token
Special characters in customer names, vendor names, or transaction descriptions may not be properly XML-encoded. Verify that the following characters are escaped correctly before importing:
-
&must be written as& -
<must be written as< -
>must be written as>
Invalid debit/credit indicators
Statement lines are missing or excluded from the import. The <CdtDbtInd> element may contain an unsupported or proprietary value instead of the expected ISO 20022 indicator. Verify that the <CdtDbtInd> element at the <Ntry> level contains a valid value: CRDT or DBIT.
Important: If the file uses a different credit/debit identifier, raise a support case with supporting documentation from your bank so the value can be added to supported identifiers.
Character encoding issues
The import fails, or characters containing diacritics (such as é, ñ, or ä) are corrupted. Verify that the XML file is saved using UTF-8 encoding and that the encoding declaration in the XML file header is consistent with the actual file encoding.
BAI2 layout and continuation-line errors
BAI2 files use a structured record-based format commonly used for bank statement processing in North America and APAC.
Broken record hierarchy
The expected BAI2 record sequence is:
-
01— File Header -
02— Group Header -
03— Account Identifier -
16— Transaction Detail -
88— Continuation Line (optional) -
49— Account Trailer -
98— Group Trailer -
99— File Trailer
Verify that there are no orphaned 16 or 88 records and that each transaction and continuation record is associated with the correct account header within the record hierarchy.
Amount or checksum mismatches
A BAI2 checksum or validation error occurs. Verify that the record counts and summary amounts in the 49, 98, and 99 trailer records reconcile with the corresponding transaction and account-level detail records.
Credits and debits are switched
Certain debit lines are imported as credit lines, or vice versa. Lines are imported as credits or debits based on their codes in the Transaction Detail line (16), where the script evaluates the first digit or first two digits. Codes starting with 9 can be particularly affected.
Important: If credits and debits are consistently switched, raise a support ticket so the code mapping can be reviewed.
Unsupported file format extensions
When importing a certain file type, ZoneReconcile may not recognise the file extension and reject the import. To add the extension to the supported list:
- As Administrator, navigate to Customization > Lists, Records & Fields > Lists.
- Click ZR Instant Upload File Type.
- In the Values list, add the file extension after the dot (for example,
940). - Click Save.
- Retry the import.
Auto-import queue stalls and script error recovery
When bank statement files are processed automatically through File Cabinet or SFTP, a malformed or corrupted file can prevent the associated Map/Reduce script from completing successfully.
Auto-import processing flow
The automated import process runs in the following sequence:
-
ZR Auto Import MR— Creates Bank Statement Auto Import records and moves files from the Unprocessed folder to the Processed folder per the Bank Statement File Processing record. -
ZR Auto Import BSTP MR— Parses each file and creates Bank Statement to Process records based on the Bank Statement Auto Import records; marks them as Processed. -
ZR Auto Import Bank Statements MR— Creates the final Bank Statement record based on the related Bank Statement to Process record and performs matching. -
ZR Process Bank Statement Transaction MR— Processes matched lines where Select is set to Yes, creates related transactions, unlocks the statement, and recalculates the NetSuite Bank Balance and Remaining Lines.
Resolving a stalled queue
- Navigate to ZoneReconcile > Bank Statement Auto Import or Bank Statement to Process.
- Filter records by Error or Unprocessed status.
- Identify records with missing Bank Account information or missing file references, which may indicate a corrupted or improperly structured source file.
- Review the associated file and error details.
- Where appropriate, mark the affected record as Processed/Invalid or remove it per your operational procedure.
- Remove the corrupted file from the File Cabinet Unprocessed folder to prevent it from being re-queued.
- Correct the source file and re-upload it for processing.
Important: ZoneReconcile evaluates only the first 500 unprocessed Bank Statement to Process records in each script run. If old, unsuccessfully imported records accumulate, they can block newer statements from being processed. Delete or inactivate Bank Statement to Process records that are no longer needed to clear the queue.
Best practices and prevention
To reduce the likelihood of malformed-syntax and parsing errors:
- Use CAMT.053 where supported — ISO 20022 XML formats provide a standardised structure and reduce delimiter-related issues associated with CSV or custom text formats.
- Standardise file encoding — Configure bank export processes to use UTF-8 encoding where supported.
- Use consistent file naming — Avoid special characters or spaces in bank statement file names deposited into SFTP or File Cabinet locations.
- Maintain validated test files — Keep a clean, known-good sample file for each bank configuration to compare against files that fail during processing.
- Validate the source file before import — Inspect the raw file for unexpected characters, missing tags, incorrect delimiters, malformed XML, or structural inconsistencies before attempting the import.