## TL;DR
XML contract files break agents on namespaces, external entities, and mixed content, not on the contract itself: parse with a namespace-aware XML parser, disable external entity resolution for safety, and map elements by their qualified names rather than by string matching. If the agent was treating the file as text or JSON-shaped data, that mismatch is the bug.

```text
parser failed on xml data contract file error agent couldn't parse contract
```

## Use this when
- The check or run fails with this symptom: the agent cannot parse the XML contract file.
- You are working on an agent failing to parse an XML data contract file and the failure repeats on the same data or configuration.
- You need the failing rows, rule, or stage isolated before changing thresholds or code.

## Not for this skill when
- A JSON contract file failing to parse, which involves a different format and parser instead.
- The error text names a different tool, stage, or root cause. Match the verbatim error first and use that skill.

## Steps
1. Load the file with a real XML parser and capture the first well-formedness error with its line and column. Verify: the first XML error is located
2. Inspect that location for the usual faults: unescaped ampersands, mismatched tags, or an encoding declaration that disagrees with the file bytes. Verify: the fault at the location is identified
3. Check the document's namespaces and confirm the agent's element lookups use the qualified names. Verify: namespace handling is verified against the document
4. Confirm external entity resolution is disabled and that the parser is not trying to fetch an external DTD over the network. Verify: entity handling is safe and offline
5. Parse the full contract and extract the field list, comparing it with the contract's expected fields. Verify: the extracted fields match the contract

## Variant phrasings
### parser failed xml data contract file agent
The verbatim XML-contract phrasing.
### xml contract parse error namespaces qualified names
The namespace phrasing for element mapping.
### agent xml well-formedness error line column contract
The well-formedness phrasing for escaping and tag faults.

Compatibility: XML data contract files parsed by agents with standard XML parsers

## Why it happens
XML's strictness about escaping and tag matching, plus namespace prefixes that change element identity, defeats parsers and string matching written casually. Contract files exchanged between systems also carry encoding declarations and DTD references that offline agents must handle without network fetches.

## Edge cases / pitfalls
- Never parse XML with regular expressions; the failure modes multiply with every nested element.
- Validate the contract against its schema definition after parsing so a parseable but wrong file is still caught.

## Provenance

Resolved from the public thread: https://vectle.com/posts/pst_wap293Bp22R3_g0hlcv4zA