Start with the bytes
Conversion failures are diagnosed faster by looking at the payload than by re-reading the configuration. The reason is that the most common causes — line endings, byte order marks, quoting, encoding — are all invisible in a rendered view.
Open the file in something that shows raw bytes or at least shows line-ending and encoding markers, and compare the beginning and the end of a record specifically. The start of the file and the end of a line are where nearly everything goes wrong.
Then work by symptom. Each of the ones below points at a small number of causes, and telling them apart is much quicker than auditing every parameter in turn.
Fields shifted or merged
Looks like: values appear under the wrong element names, or two fields are concatenated into one. Every field after the problem is offset by one position.
Usual cause: the field separator does not match the file, or the file contains a quoted field holding the delimiter and no enclosure is configured. A record like 1004,"Smith, John",BR-223 splits into six fields instead of five when quoting is not declared.
Check: the fieldSeparator value against the real file, then whether any field in the source is quoted. Both are covered in the parameter reference.
This is the failure that costs the most, because the record still parses and the XML is still well-formed. Nothing errors; the values are simply wrong.
Last field carries junk
Looks like: the final field of every record contains an invisible extra character, or fails to match a lookup that it visibly should match.
Usual cause: a carriage return. The file was written with \r\n line endings but the end separator accounts only for the newline, so the \r attaches to the last field.
Check: the raw bytes at the end of a line, not the rendered text. Note that nl is only valid in endSeparator; use \n elsewhere.
First element name is wrong
Looks like: the first element or first field name in the output is subtly different from what you configured — often with characters that are not visible.
Usual cause: a byte order mark. A UTF-8 file saved with a BOM begins with three bytes that are invisible in an editor and become part of the first name.
Check: the first three bytes of the file. Re-saving without a BOM fixes it at the source, which is usually better than compensating in the configuration.
Characters arrive garbled
Looks like: accented or non-Latin characters arrive as nonsense sequences, or processing stops on a byte it cannot map.
Usual cause: the channel encoding does not match the file. UTF-8, ISO-8859-1 and platform-specific character sets all produce different results from the same configuration.
Check: what the sending system actually writes, rather than what it is documented to write. These differ more often than anyone expects.
Key field errors
Looks like: the adapter refuses the configuration, or records are parsed as the wrong type — a trailer line treated as data, a header treated as a record.
Usual cause: a key field is required because a node has unlimited cardinality, and it is missing or does not appear in every substructure. Alternatively the keyFieldValue does not match what the file actually contains.
Check: that the key field exists in all substructures, and compare its value against the raw file rather than against a sample someone typed into a document.
Records in the wrong order
Looks like: the data is recognisably yours but organised wrongly — records merged, or attributed to the wrong node.
Usual cause: Recordset Sequence. Ascending assumes the structures appear in the order you declared them; Variable does not. Using Ascending on an interleaved file produces exactly this.
Missing or null records
Looks like: the first record of the XML is your header labels, or records are missing from the output.
Usual cause: Document Offset. It defaults to zero, so a header row is parsed as data. Where records are missing entirely, look at Recordsets per Message — a low value splits one file into several messages, and only the first may be visible where you are looking.
An empty field in the middle of a record is a separate case: confirm whether it is being preserved or silently dropped, because the answer differs with the format and matters to the receiver.
It fails later, in the mapping
Looks like: the channel is green, but the mapping throws — an unexpected element, a missing node, a value that cannot be converted.
Usual cause: the Document Name and Namespace do not match the message type in the Integration Repository, so the mapping resolves against nothing. Or the node names in the Recordset Structure do not match the element names the mapping expects.
Check: the generated XML itself, before the mapping runs. The node names in your configuration are a contract with the mapping, and a mismatch surfaces here rather than at the channel.
The general rule: if the incoming XML is not shaped the way the mapping expects, the problem is upstream of the mapping.
Works in test, fails in production
The single most common version of this problem is encoding, and the second is file size. Neither is a mapping fault, and neither will reproduce if you test with a hand-written sample.
Test with genuine files from the sending system — including the largest one you expect, and one containing characters outside ASCII. If it fails only in production, the difference is almost always the file, not the configuration.
To see the parameters these symptoms point at, go to the parameter reference, or back to the overview.