SOAPless
Sign Up
Back to Blog
soap-errorswcfxml

The formatter threw an exception while trying to deserialize the message: How to Fix It

SOAPless Team3 min read

This error is usually a WCF-side way of saying: your XML body did not match the contract.

The formatter threw an exception while trying to deserialize the message

You may also see extra detail such as:

There was an error while trying to deserialize parameter

That second line matters. It usually means the server got your SOAP request and failed while binding one specific parameter.

What breaks deserialization most often

  • wrong wrapper element name
  • wrong namespace URI
  • body contains an object where the contract expects a primitive
  • array vs single-item shape mismatch
  • nillable / optional fields sent in the wrong form

Example: wrapper mismatch

Suppose the contract expects:

<tns:GetCustomer xmlns:tns="http://example.com/contracts">
  <tns:id>42</tns:id>
</tns:GetCustomer>

But your request body sends:

<GetCustomerRequest xmlns="http://example.com/contracts">
  <id>42</id>
</GetCustomerRequest>

That is enough to trigger the formatter exception.

How to isolate the bad field quickly

Start from the smallest valid request you can build and add fields one by one.

curl -s https://example.com/service.svc?wsdl -o service.wsdl

Then inspect:

  • the operation element name
  • parameter order
  • whether child fields share the same namespace
  • whether repeated fields are expected as arrays

If the service works in SoapUI but not in code, export the raw request from SoapUI and diff it against your generated XML.

Watch for array vs scalar drift

This is common when JSON is converted into SOAP XML by hand.

Expected:

<tns:tags>
  <tns:string>red</tns:string>
  <tns:string>blue</tns:string>
</tns:tags>

Broken:

<tns:tags>red</tns:tags>

The service contract is strongly typed. A shape mismatch often turns into a generic formatter exception instead of a helpful validation error.

If the error mentions a specific parameter

When you get a more verbose message like:

There was an error while trying to deserialize parameter http://example.com/contracts:request.
The InnerException message was 'Element 'id' contains data from a type that maps to the name 'string'.

focus on that one parameter first. The failing parameter is rarely random.

Shell-first debugging loop

Use a local request file so you can iterate without touching app code:

curl -v https://example.com/service.svc \
  -H 'Content-Type: text/xml; charset=utf-8' \
  --data @request.xml

Edit request.xml, rerun, and compare server behavior. This is faster than guessing from generated client abstractions.

The structural fix

If you have multiple jobs, scripts, or services talking to the same SOAP endpoint, every one of them becomes another place where wrapper names and namespaces can drift.

That is why teams eventually put a proxy in front of the SOAP service: one place owns the XML contract, while application code talks JSON.

Back to Blog