How to Fix Special Character Errors in MuleSoft XML Parsing

If you work with MuleSoft, you know that XML data can be a bit temperamental. One moment everything is flowing perfectly, and the next, your integration crashes because of a single, tiny character.

Specifically, the ampersand (&) is a notorious troublemaker. When this character appears in your data without being properly "escaped" (converted to a code the computer understands), it breaks the XML structure. This leads to parsing errors and the dreaded com.ctc.wstx.exc.WstxLazyException.

Don't worry—this is a very common hurdle for developers. In this guide, we will look at how to identify the problem and use a reliable DataWeave script to fix it permanently.

The Problem: Unescaped Characters

Imagine you are processing a product catalog. The XML parser expects a clean, rigid structure. However, if it hits a special character that it thinks is part of the code (like an ampersand), it gets confused and throws a fit.

You will typically see an error message that looks like this:

Error: [com.ctc.wstx.exc.WstxLazyException] Unexpected character '<' (code 60) (expected a name start character) at [row,col {unknown-source}]: [5,34].

Here is the exact XML example causing the crash. Pay close attention to the <item_number> tag in the first catalog item.

The "Broken" XML Input

<?xml version="1.0" encoding="UTF-8"?>
<catalog>
    <product description="Cardigan Sweater" product_image="cardigan.jpg">
        <catalog_item gender="Men's">
            <!-- The error is right here: The '&' is raw, not escaped -->
            <item_number>QWZ5671&</item_number>
            <price>39.95</price>
            <size description="Medium">
                <color_swatch image="red_cardigan.jpg">Red</color_swatch>
                <color_swatch image="burgundy_cardigan.jpg">Burgundy</color_swatch>
            </size>
            <size description="Large">
                <color_swatch image="red_cardigan.jpg">Red</color_swatch>
                <color_swatch image="burgundy_cardigan.jpg">Burgundy</color_swatch>
            </size>
        </catalog_item>
        <catalog_item gender="Women's">
            <item_number>RRX9856</item_number>
            <price>42.50</price>
            <size description="Small">
                <color_swatch image="red_cardigan.jpg">Red</color_swatch>
                <color_swatch image="navy_cardigan.jpg">Navy</color_swatch>
                <color_swatch image="burgundy_cardigan.jpg">Burgundy</color_swatch>
            </size>
            <size description="Medium">
                <color_swatch image="red_cardigan.jpg">Red</color_swatch>
                <color_swatch image="navy_cardigan.jpg">Navy</color_swatch>
                <color_swatch image="burgundy_cardigan.jpg">Burgundy</color_swatch>
                <color_swatch image="black_cardigan.jpg">Black</color_swatch>
            </size>
            <size description="Large">
                <color_swatch image="navy_cardigan.jpg">Navy</color_swatch>
                <color_swatch image="black_cardigan.jpg">Black</color_swatch>
            </size>
            <size description="Extra Large">
                <color_swatch image="burgundy_cardigan.jpg">Burgundy</color_swatch>
                <color_swatch image="black_cardigan.jpg">Black</color_swatch>
            </size>
        </catalog_item>
    </product>
</catalog>

The Solution: DataWeave to the Rescue

To fix this, we need to intercept the data before the parser chokes on it. We can use a DataWeave (DW) script to read the raw text stream and replace those tricky characters programmatically.

Here is the exact script you need to solve this issue:

%dw 2.0
output application/xml
---
read(payload.^raw replace '&' with "&" replace "&" with '&', 'application/xml')

How It Works

This script performs a clever "clean-up" operation in three distinct steps:

1. Read Raw Data: The function payload.^raw tells MuleSoft to look at the input as a stream of raw text bytes, rather than trying to parse it as XML immediately. This prevents the crash from happening before we can fix it.
2. Smart Replacement: The replace function is used twice to ensure data integrity:
   • First Pass: It replaces existing & entities with &. This resets everything to a base state so we don't accidentally double-encode something that was already correct (turning & into &).
   • Second Pass: It takes all & characters (including the ones we just reset) and turns them into &. This ensures every ampersand is now properly escaped.
3. Final Output: The read(..., 'application/xml') function wraps the sanitized text and outputs valid, error-free XML that your application can finally use.

By implementing this logic, you prevent special characters from breaking your flow, ensuring your MuleSoft application processes catalog data smoothly every time.