Quick wins for a faster PC:
Scan for outdated or missing drivers - takes under a minuteDriver Scan →Repair Windows errors before they cause bigger problemsFix Now →Inspect the raw HTTP response before changing the client: WstxUnexpectedCharException means Woodstox encountered a character it could not accept at that point in the XML, and CXF may surface the parsing failure as a SOAPFaultException. A control character inside the payload points toward invalid serialized data; an unexpected character in the prolog often means the response is not XML at all.
What the exception means
WstxUnexpectedCharException is a Woodstox XML-parsing exception. Woodstox describes it as an unexpected character that is not legal in the parser’s current context; it may be invalid, or simply in the wrong place. The parser reports a location to help identify where it failed.
SOAPFaultException is the outer JAX-WS error a CXF client can expose when the XML reader or JAXB unmarshaller fails. The exception name alone does not establish that the server sent a valid SOAP fault. The defect to investigate is usually in the response bytes or characters reaching the parser.
First determine where parsing failed
The parser location and reported character are the quickest clues. Compare them with the actual response body rather than inferring the cause from the wrapper exception.
Recommended Free Tools
| Clue | Likely problem | Where to investigate |
|---|---|---|
| A control character is reported at a location inside element text | Response content contains a character forbidden by the XML version in use. | Service data, serialization, or a transformation that modifies the response. |
| An unexpected character is reported in the prolog, before the XML document begins | The response may be HTML or plain text, or the XML prolog may be malformed or preceded by stray bytes. | HTTP response, fault handler, authentication layer, proxy, or gateway. |
Illegal character inside XML text
An error such as Illegal character ((CTRL-CHAR, code 23)) pointing into element content indicates that the producer emitted a character XML does not permit there. Apache CXF issue CXF-1771 demonstrates this failure with control character 23 appended to a Java String: JAXB unmarshalling fails on the client and the error surfaces as a SOAPFaultException.
Fix the data or the layer that serializes or transforms it. Remove characters disallowed by the applicable XML version, and validate the serialized response before sending it. An XML entity is not a way to represent every forbidden control character: use an entity only when the character is legal under the XML version in use. Catching the client exception does not make malformed XML valid.
Rank #2
Unexpected character in the prolog
A message such as Unexpected character '-' (code 45) in prolog; expected '<' at row 2, column 1 means the parser expected the start of an XML document and encountered a hyphen instead. CXF issue CXF-7952 records that pattern for a malformed SOAP fault. Similar symptoms can occur when a proxy, gateway, authentication layer, or application server returns HTML or plain text instead of SOAP XML. CXF’s debugging guidance specifically notes that a client may receive an HTML error message it cannot normally process.
Find which hop generated the body. Check the HTTP status and Content-Type, the URL after redirects, authentication failures, and any proxy or gateway substitutions. Confirm whether the body begins with XML and whether a UTF-8 BOM or other stray bytes precede the opening <. Woodstox’s reported prolog character and location make inspection of the raw body decisive.
Diagnose the response before changing code
- Capture the response. Enable secured CXF wire logging or otherwise capture the raw HTTP response before unmarshalling. CXF documents SOAP-message inspection as a debugging method; protect logs because SOAP bodies can contain sensitive data.
- Record the HTTP exchange. Note the status, response headers, final URL after redirects, and the first 100–200 bytes of the body. Check that the content is actually SOAP XML rather than an intermediary’s error page or message.
- Match the parser location to the body. Compare the reported row, column, and character code with the captured response. A control code within element text suggests invalid serialized content; a failure near row 1 or 2, column 1 points toward a non-XML response or a malformed prolog.
- Validate XML well-formedness. Parse the captured response independently before JAXB mapping. Check the XML version, declared encoding, namespace declarations, and closing tags, as well as any bytes before the document starts.
- Separate server output from client behavior. Reproduce the request to the same endpoint with a SOAP test client, preserving relevant authentication and headers. Compare the received response with the generated client’s response path to identify whether transport behavior or an intermediary changes it.
- Fix the component that produced the bad response. Correct the service data, serializer, fault handler, proxy, or gateway as indicated, then retest the exact route used by the application.
Choose the fix based on the source
If the bad character is in service data
- Identify the field and upstream value containing the disallowed character.
- Remove or safely transform characters that the XML version forbids before serialization; validate the resulting XML at the service boundary.
- Check transformation and fault-generation code too: a response can become malformed after the original data is prepared.
If the response is not XML
- Use the recorded status, headers, final URL, and body to locate the component returning the HTML or plain-text response.
- Resolve the underlying HTTP, authentication, redirect, proxy, gateway, or server-fault problem so the endpoint returns the expected SOAP response.
- If a SOAP fault is intended, correct the fault serializer or handler so it emits well-formed XML.
If the prolog is malformed
- Inspect the exact leading bytes for stray output, an unexpected prefix, or encoding/BOM handling that does not match the document declaration.
- Correct the response generation or intermediary that adds or alters those bytes, then validate the complete response rather than only its SOAP body.
Use CXF fault diagnostics carefully
CXF documents the faultStackTraceEnabled property for including server stack traces in fault details and exceptionMessageCauseEnabled for embedding the cause message. These can help diagnose a server-side fault in a controlled environment, but stack traces and cause messages can reveal implementation details. Do not expose them in production responses to untrusted clients.
When to consider a library upgrade
Investigate the response producer or intermediary before treating this as a Woodstox bug. The cited CXF issue reports concern older CXF and Woodstox generations, while parser behavior and deployed combinations can vary. Check the CXF, Woodstox, JAX-WS/JAXB, proxy, and gateway versions in the affected path. Consider a version-specific change only when relevant release notes or a minimal reproduction show that the deployed parser mishandles otherwise valid XML.
Quick Recap
Best Value
Rank #4
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
