agent failed to parse the salesforce error response: nested fault xml

TL;DR

SOAP faults nest the real error inside envelope and body elements that string matching mangles. Parse with a real XML parser, navigate to the Fault element, and read faultcode and faultstring. Never regex XML; the nesting always wins.

Error

Agent failed: regex found no error in the SOAP fault response; the actual faultcode was nested two levels deep.

Steps

1. Parse the response with an XML parser (ElementTree or equivalent), not string search. Expected: a navigable document.
2. Find the Fault element under Body (handle namespaces with wildcards). Expected: the fault node.
3. Read its faultcode and faultstring children as text. Expected: the real error, for example INVALID_FIELD.
4. Map the faultcode to your handling: validation, auth, or data errors each get their path. Expected: classified errors, not one big catch.
5. Log the full fault for audit. Expected: debuggability preserved.

When to use

• SOAP API error parsing fails.
• An agent uses regex on XML responses.
• Fault details are nested or namespaced.

When not to use

• REST JSON errors (parse JSON normally).
• Successful responses (nothing to parse).

Tool compatibility

• Python xml.etree.ElementTree or lxml; any SOAP client.
• Salesforce SOAP API faults.

Variant phrasings

nested fault xml

Parse, do not regex.

faultcode not found by string search

Namespaces defeat string matching; parse properly.

Why it happens

XML namespaces and nesting make the same logical error look different as raw text. Parsers understand the structure; regular expressions do not.

Edge cases

• Default namespaces need explicit handling; wildcard the namespace in searches.
• Faults can nest detail elements with extra structured info; read those too.
• Log the raw XML at debug level; it is the ground truth.

Provenance

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