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

Posted: January 26, 2016 in BizTalk
Tags: , , , , , ,

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 where 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.


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 particular distinguished field it was not being used inside the orchestration!


The solution it 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 ma 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”
  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.

    • 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.

      • Leonid Ganeline says:

        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…”

      • Agree with you on that Leonid. I will always prefer to use XPATH expressions instead of distinguished fields.

  2. “The recommendation might be “never use it”🙂

    • Leonid Ganeline says:

      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

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s