XLANG Uncaught exception: A failure occurred while evaluating the distinguished field [MY_FIELD_NAME] against the message part data.

Well let’s go back to the topic: you are doing crazy things with your maps!

I was thinking that I had already seen it all, I was thinking that I had already seen it all, but the reality is that I continue to be blown away. While testing a project migration I end up catching this error:

Xlang/s engine event log entry: Uncaught exception (see the ‘inner exception’ below) has suspended an instance of service ‘[MY_ORCHESTRATION_NAME] (1582c665-816d-07db-3dee-1c6a750944a0)’.
The service instance will remain suspended until administratively resumed or terminated.
If resumed the instance will continue from its last persisted state and may re-throw the same unexpected exception.
InstanceId: 4e0d3e55-b481-442d-a2a4-9f4ee6e13fb7
Shape name: Create Client Msg
ShapeId: 0e4a8cba-c6a0-4a0f-ad94-574b2e8ab7ad
Exception thrown from: segment 1, progress 54

Inner exception: A failure occurred while evaluating the distinguished field [MY_FIELD_NAME] against the message part data. The message part data does not contain at least one of the nodes specified by the XPath expression (listed below) that corresponds to the distinguished field. The cause for this error may be that the message part data has not been initialized or that the message part data does not conform to the message part schema. Ensure that the message part data is initialized correctly. XPath expression: /*[local-name()=’ROOT_NAME’ and namespace-uri()=’NAMESPACE’]/*[local-name()=’MY_FIELD_NAME’ and namespace-uri()=”]

Exception type: XPathUpdateException
Source: Microsoft.XLANGs.Engine
Target Site: Void SetDistinguishedField(System.String, System.Object)
The following is a stack trace that identifies the location where the exception occurred
at Microsoft.XLANGs.Core.XSDPart.SetDistinguishedField(String dottedPath, Object val)
at Siva.CRM.EAI.SIVOrchestration.Client.SIV_Client_ClientAccountSubscriber_UpdDel.segment1(StopConditions stopOn)
at Microsoft.XLANGs.Core.SegmentScheduler.RunASegment(Segment s, StopConditions stopCond, Exception& exp)

I got curious to see that this problem, as the error specify clearly, was related to a distinguished field element and it was happening inside a Construct Message that was using a map.


The error details points for the cause of the problem and it is for sure something related to the XPath expression: /*[local-name()=’ROOT_NAME’ and namespace-uri()=’NAMESPACE’]/*[local-name()=’MY_FIELD_NAME’ and namespace-uri()=”], however, the cause may not be exactly the same.

In my case when I opened the map, I easily realize that the field that was promoted as distinguished field was being mapped twice, i.e., two source elements were being mapped to the same destination element what was causing this element to appear twice in the final message even though the destination element is defined as Max Occurs 1 and Min Occurs 0.

wrong transformation rule causing error evaluating distinguished field

Of course, you may know that distinguished fields are essentially XPath aliases, which simply point to the appropriate XML data field. They don’t have a size limitation but they only can appear once. You cannot promote a repeating element.

And you also should know that the map doesn’t validate the input or the output messages in runtime!

And the curious thing was that this particularly distinguished field it was not being used inside the orchestration!


The solution is easy for this case.


  • Don’t promote elements that you are not really using or need to do some logic inside your orchestrations… If you don’t need them, don’t promote them. Distinguished fields cost less than Property Fields but they still have a cost for performance!


  • Fix the mapping rule associated with this element. In my case, I decide to remove the “nipc” rule and leave only the “accountId” direct link to the “EntityGuid”
Author: Sandro Pereira

Sandro Pereira lives in Portugal and works as a consultant at DevScope. In the past years, he has been working on implementing Integration scenarios both on-premises and cloud for various clients, each with different scenarios from a technical point of view, size, and criticality, using Microsoft Azure, Microsoft BizTalk Server and different technologies like AS2, EDI, RosettaNet, SAP, TIBCO etc. He is a regular blogger, international speaker, and technical reviewer of several BizTalk books all focused on Integration. He is also the author of the book “BizTalk Mapping Patterns & Best Practices”. He has been awarded MVP since 2011 for his contributions to the integration community.

6 thoughts on “XLANG Uncaught exception: A failure occurred while evaluating the distinguished field [MY_FIELD_NAME] against the message part data.”

  1. Hi Sandro.
    We also had this error message regarding fields that are not mandatory or fields that didn’t have a standard value assigned in the mapping. And in case the mapping doesn’t fill the field with a proper value, the XPATH Expression has failed in the Orchestration as well.
    In our special case we didn’t map the field in the mapping, so it wasn’t part in the target message. So our solution was to fill that field with a dummy value in the mapping. So it is then accessible in the Orchestration and we could assign a new value in in a message assignment within the Orchestration. Maybe that can be helpful for users who have that same error.

    1. indeed this can be another problem. The solution there is to query the data before and pass it to the map (two message input to the map) or add a default “dummy” value and afterward field the element with the proper data.

      1. The simplest way to deal with limitations of the distinguished fields is to use xpath. With it we have full control of the logic. Say we could get the first element, second or any other element in collection or verify the element for existence without trouble with exceptions. Distinguished field is a simple limited replacement for xpath. And frankly I don’t understand we it was introduced. The recommendation might be “never use it” 🙂 The most damaging thing it would cause on the interview questions with infamous “what the difference between promoted and distinguished…”

    1. For complex transformation the price of using Mapper could be too high. The same might be for xslt, which is very hard to debug.
      I prefer (if I have a choice, which is almost “never” 🙁 ) to use plain .NET. BTW It is almost always faster. But the best part of using it is: *all* developers could support it, not just xslt or BizTalk aficionados as us 🙂

Leave a Reply

Your email address will not be published. Required fields are marked *


Back to Top