If you’ve been around BizTalk for a while, like me, you most certainly have gotten this error many times.

The normal solutions are:
1) Make sure you schema is deployed
2) Make sure your schema is not deployed more than once
3) Set “AllowUnrecognizedMessage” to True in the XML Disassembler.
4) Make sure the file you dropped has the proper namespace and root element.

To review, in BizTalk MessageType is the TargetNamespace#RootElement.

Here was the exact message I got when I dropped my test file:

The Messaging Engine failed while executing the inbound map
 for the message coming from source URL:"e:\Integration\Inbound\CPChemNew\204\*.xml" 
 with the Message Type "http://abc.com/X12/204/CPChem2#X12_00401_204". 
Details:"Finding the document specification by message type "ST" failed. Verify the schema deployed properly. " 

The message type looked okay.

But what was this "ST" in the second message?


I was converting a regular schema to an envelope schema in order to accomplish debaching. "Body XPath" is a parm you set so that the receive XML pipeline will automatically split the message into multiple messages).

I put the "Body XPath" one element too low. It should have split on X12_00401_204, but actually split the message into an ST, and other similar segments.


Here's what I didn't understand. I'm not sure why, but after debatching, the XML Disasembler on the Receive Pipelines, decides that it needs to verify that the target schema exists as well. Thus, the error on "ST".

How I Solved It

1. I did a test map in Visual Studio and got the results of the test map.
2. And then dropped that into the appropriate Receive Location (different from the one above).
3. Since I had tracking turned on, I check the "Tracked Message Events", and saw multiple "Transmission Failed" and looking at the body of each, I see one file has as the root, one has as the root, and so on.
4. The other thing I should have noticed was that in the error, the message type should have been: "http://abc.com/X12/204/CPChem2#X12_00401_204Looping" instead of "http://abc.com/X12/204/CPChem2#X12_00401_204". That should have hinted to me that maybe the debatching was happening. X12_00401_204Looping and X12_00401_204 were so similar I didn't notice, so lesson learned here is don't assume and be exact.

The file I'm trying to build looks like this:

<ns0:X12_00401_204_LOOPING xmlns:ns0="http://abc.com/X12/204/CPChem2">

In EDI, a customer can send multiple 204s, but we wanted a single file with multiple 204s in it (too complex to explain here).

The next thing I need to do is make sure I have a scheme that matches , and I need to add a namespace to that as well. So more work to be done, but now I'm back on track. What I need is two schemas, and the Envelope schema can import and reference the other one.

Full Error

System.InvalidCastException: Failed to convert parameter value from a String to a IEnumerable`1.
—> System.InvalidCastException: Invalid cast from ‘System.String’ to ‘System.Collections.Generic.IEnumerable`1
[[System.Data.Common.DbDataRecord, System.Data, Version=, Culture=neutral, PublicKeyToken=b77a5c561934e089]]’.
at System.Convert.DefaultToType(IConvertible value, Type targetType, IFormatProvider provider)
at System.Convert.ChangeType(Object value, Type conversionType, IFormatProvider provider)
at System.Data.SqlClient.SqlParameter.CoerceValue(Object value, MetaType destinationType, Boolean& coercedToDataFeed, Boolean& typeChanged, Boolean allowStreaming)
— End of inner exception stack trace —


We use SQL User-Defined-Types to pass XML data from BizTalk to SQL stored procs.
I had to build a custom EDI schema to change the inbound validation for a field.

In this particular project, the EDI pipeline had “Preserve Interchange” set to true.
I knew there was a map in my project on this data, but the map itself used a special little schema that supported the “Preserve Interchange” format.
So I think I might get lucky, and just be able to deploy the schema.

Well – the map used XSLT, and the XSLT had the namespace of the schema.
So although the map ran, it was generating a call to the stored proc that had no data, i.e. the User-Defined-Type didn’t get mapped under the root element.
That caused the odd validation error above!

In Summary – the namespace in the XSLT did not match the namespace specified in the Party/Agreement configuration.  Thus the output of the map had a root element, but none of the User-Defined-Type elements.

BTDF deploy on local machine in Visual Studio by using “Tools”, “Deployment Framework for BizTalk”, “Deploy BizTalk Solution” failed with the following error in XmlPreprocess.exe

/s:: Argument expects a parameter

What caused the error for me was that I in the SettingsFileGenerator.xml spreadsheet, I had renamed all the “Settings File Names” for each environment.  I switched the “Local Development” back to Exported_LocalSettings.xml and this got around the issue.

Perhaps there is a setting in the .btdfproj file that allows you to specify (override) the local settings name, but I couldn’t find it today.




Error text:

A message sent to adapter “FILE” on send port “spGwCustomers_Caterpillar_EDI210” with URI “C:\Integrations\EDI1\Customers\xxxx\outbound\210\Test_210_%datetime_bts2000%.TXT” is suspended.
Error details: The system cannot find the file specified. (Exception from HRESULT: 0x80070002)


The file not found can refer to the map .dll. The error to me is quite misleading, because it implies the directory/filename path listed in the error is the problem.
This can happen to me when I don’t run the MSI (or other deploy process) for a map on one of the BizTalk servers (when you have multiple BizTalk servers in the same group).

It sure would be nice if the error would give the actual missing filename (i.e. the map .dll name).


Got the following error when posting to a BizTalk receive location from SOAP-UI, but could have happened with any type of receive location:

HTTP/1.1 500 Internal Server Error
Content-Type: application/xml; charset=utf-8
Server: Microsoft-IIS/8.5
X-Powered-By: ASP.NET
Date: Thu, 05 Jul 2018 14:07:37 GMT
Content-Length: 2384

<Fault xmlns="http://schemas.microsoft.com/ws/2005/05/envelope/none"><Code><Value>Receiver</Value><Subcode>
<Value xmlns:a="http://schemas.microsoft.com/net/2005/12/windowscommunicationfoundation/dispatcher">
a:InternalServiceFault</Value></Subcode></Code><Reason><Text xml:lang="en-US">
There was a failure executing the receive pipeline: 
"MyPipeline, etc... Version=, Culture=neutral, PublicKeyToken=1234123412341234"
 Source: "XML disassembler" Receive Port: "rpFrontEnd_TLRGLoadTenderOut_Web" 
 URI: "/TLRG/Shipment/DirectTender.svc" 
 Reason: Finding the document specification by message type 
 "http://myNamespace#MyRootNode" failed. 
 Verify the schema deployed properly.  </Text></Reason><Detail><ExceptionDetail 


This was a conversion from old 2010 system to 2013. On the first pass, I had forgotten a map that trimmed all the fields and removed empty nodes. The map used XSLT, and in the XSLT source, it had the wrong namespace from the old system.

Other Hints

Remember MessageType = NameSpace#Root

  1. Make sure the schema is really deployed (BizTalk Admin console)
  2. Check your spelling carefully, look for typos.
  3. If you have a map in the receive location, make sure the map is really running. I.e. does the messageType of the incoming message match the map. If the map doesn’t match, the incoming message will be passed on and could get this error.
  4. If you have a map, make sure the map has been tested and outputs the correct messageType.
  5. If you are doing JSON to xml (or any other file format to XML, make sure the pipeline is creating the correct messageType.
  6. Of course, make sure you restarted your Host Instances
  7. Check your values in BizTalk Admin before and after each deploy. If you are doing some kind of automated deploy, make sure your bindings for that deploy are current; they maybe resetting some value each time you deploy. In my case, I had a script to export the bindings, but I was actually running a similar script for another project. So everytime I reset the namespace value for the RootNodeNamespace in the JSON pipeline, it was getting reset on each re-deploy.


Microsoft.ServiceModel.Channels.Common.ConnectionException: Login failed. The login is from an untrusted domain and cannot be used with Windows authentication.
—> System.Data.SqlClient.SqlException: Login failed. The login is from an untrusted domain and cannot be used with Windows authentication.

The user was correct, and that was driving me crazy. I had just built the database from a script, and I set and double-checked the security in SSMS for that database.
I’m running on my own VM on my desktop; and the userid is my VM-Name/bts_host_ins (and that’s the user that all the host instances run with).


There could be other reasons for this error, but here was my reason…

My SendPort was pointing to our development system which is on the “DEV” domain, and my VM where I’m testing is on the primary domain.
The fix was just to repoint the SendPort to my local VM which is what I wanted anyway. If I really did want to go to the DEV domain, then I would have to use a user on that domain to run my host instance.


The adapter failed to transmit message going to send port “sp_Test_SFTP” with URL “sftp://sftp.mycompany.com:22/%MessageID%.xml”. It will be retransmitted after the retry interval specified for this Send Port. Details:”System.IO.FileLoadException: Could not load file or assembly ‘WinSCPnet, Version=, Culture=neutral, PublicKeyToken=2271ec4a3c56d0bf’ or one of its dependencies. General Exception (Exception from HRESULT: 0x80131500)
File name: ‘WinSCPnet, Version=, Culture=neutral, PublicKeyToken=2271ec4a3c56d0bf’ —> System.Exception: SFTP adapter requires WinSCP to be installed. Please refer http://go.microsoft.com/fwlink/?LinkID=730458&clcid=0x409 . —> System.IO.FileNotFoundException: Could not load file or assembly ‘file:///C:\Windows\Microsoft.Net\assembly\GAC_MSIL\Microsoft.BizTalk.Adapter.Sftp\v4.0_3.0.1.0__31bf3856ad364e35\WinSCPnet.dll’ or one of its dependencies. The system cannot find the file specified.


I think BizTalk requires a specific older version of WinSCP and you can’t just download the latest one.
This error could also occur if you didn’t copy the file to the proper directly.

I found Michael Stephenson’s BizTalk 2016 SFTP blog, and it had a nice PowerShell script.

I just had to
1) Change directory names (I had a Software directory similar to him, but I had to create a WinSCP subdirectory under it)
2) Then PowerShell with the “Run as Admin” option.

Then the script ran fine, I restarted BizTalk Host Instance, and it got past this error, on to other errors that I’ll blog about in the near future.

By the way, I was able to run in a 64-bit host with no problem.  I remember that in older version of BizTalk the FTP adapter ran only in 32-bit hosts.




Error: Root Element is Missing

InstanceId: d1c2f87c-825b-4c6e-b01c-c93e50d63502
Shape name: msgABCDetail
ShapeId: 33d0d3ac-ae45-408c-8224-f42725877a2b
Exception thrown from: segment 4, progress 22
Inner exception: Root element is missing.


This error occurs in an orchestration, typically after you have run a map, and the map doesn’t create any output.

The map is in a construct statement, and presumably the message created in the construct statement should not be empty.

The way to test or fix this is as follows:

1) Obtain a copy of a the message that goes into the map (might have to add debug or write message to disk or trace), and save to disk.

2) Test that message in Visual Studio using the right click “Test Map” option on the map (first set the “TestMap Input Instance” property to the filename you saved from the step above.

3) Typically the issue is a namespace or higher level node is missing. This causes none of the xpaths in the XSLT to match, and thus nothing is generating on the “right side” of the map. When you test the map, the Output window will show something like this: “The output is stored in the following file: xxx.xml”. If you cntl-click on that file, that file will open. In all likelihood it will be empty (blank). [If it has data in it, there is a chance the code you are running doesn’t match the current version of the source code/map you are testing, indicating you might need to redeploy.]

4) To check further, you can also check the file against the schema, to make sure it is valid. This may help indicate an element name or namespace that is wrong that could cause the map to result in empty output. Set the schema property “Input Instance Filename”, then right click on the schema and select “Validate Instance”. If it fails, you might try generating an instance, then use a file compare or your own eyeballs to compare the generated instance to the instance you were validating (experience teaches you what to look for).

Here’s a specific case I dealt with today. My data file had a root element named eisresultset. It was built by xpathing to a node of the data data returned to us by a vendor. Due to the way the vendor packs the data in a generic XmlDoc packet, the WSDL did not build the schemas for us, and I had to do it manually. When I built the schema for esiresultset, I misspelled the root element name and had esiresultset. The reversal of those two letters make a huge difference!

When I validated the data instance against the schema, the output window told me clearly:
e:\MyDir\MySubDir\map_EsiResultSet_To_DBTableMotoDetails_TestIn1.xml: error BEC2004: The ‘eisresultset’ element is not declared.

The second mistake I made, was in my map, I had mapped eisrecord, a separate schema with that repeats inside of eisresultset. So mapping a schema that starts with a higher level element than what I mapped would never result in a good map output.

This is a “back to the basics” post with a list of reasons BizTalk might not be processing (consuming) your file that you have placed (dropped) in a directory associated with a Receive Location.

1. Are the Host Instances started? (Specifically the Host Instance associated with the Receive Location).  Be sure and refresh (F5 or right-click refresh) to make sure you are not looking at old statuses.

Each receive location has a “Receive Handler”. See Figure 1 below.

See Figure 2 below to check if the Host Instances are started. Be sure and refresh (F5 or right-click refresh) to make sure you are not looking at old statuses.

Figure 1 - Receive Location - Receive Handler (Host Instance)

Figure 1 – Receive Location – Receive Handler (Host Instance)

In the case above, the Receive Location Hander is BizTalkServeApplication. So it doesn’t matter that the Rosetta Host Instance is not started.

Figure 2 - Status of Host Instances

Figure 2 – Status of Host Instances

2. Make sure the Receive Location itself is “Enabled”. The figure below doesn’t show, but I opened BizTalk Admin console, navigated to the Application on the left menu, then expanded the “Receive Locations”

Figure 3 - Receive Location Status

Figure 3 – Receive Location Status

3. Check Windows Application Event Viewer for Errors:

For example, here is an error I had today:
The FILE receive adapter cannot process file e:\Messages\Charter\Inbox\StarterParams\StartParams_Prod.xml because of one of the following reasons:
1) The file is read-only.
2) The file is a system file.
3) The FILE receive adapter does not have write permissions on the file.

To see if the file is read only, right click on the file and make sure the checkbox next to “read-only” attribute is NOT checked. Also make sure the file you are copying/dropping into the pickup directory is not “read-only”, because that attribute sticks when you copy it. NOTE: You might have a sample file in your Visual Studio Project, then when you check that project in to TFS (or some other source control system), the read-only attribute of that file is turned on. You might want to have a copy of your file for testing that is not part of TFS check-in so that the read-only attribute will stay off.

To check security, from Windows Explorer, right click the directory (not the file), click on the Security tab, and make sure that the userid that runs the Receive Handler Host Instance (see Figures 1 and 2 above) have Full Control. If in doubt, you could always add the user “Everyone” and give it full access. Then once you get it working, go back and tighten-up the security. If you are working on your own laptop or development computer, the security probably doesn’t matter. But on a shared development, QA, or production environment, security can be very important.

4. Consider checking the CPU performance on the machine.

I’ve seen cases where there is a task using 100% of the CPU, and that is preventing the BizTalk host instance to do its work.

The short cut to open Windows Task Manager is Cntl-Shift-Escape.  I like to check the “Performance tab” to see what CPU Usage is, if it is high, and how long it has been high. If it is really high, like 90-100%, you can click Processes (then sort by CPU) and find out which task is taking all the CPU.

Figure 4 - Windows Task Manager

Figure 4 – Windows Task Manager


When I treid to start a project, several SendPorts would not start.  When I tried to start each one manually, some of them were giving this misleading error in the EventLog.

Unable to communicate with MessageBox BizTalkMsgBoxDb on SQL Instance DAL-BIZ-APP01. Error Code: 0x8004d00e. Possible reasons include:
1) The MessageBox is unavailable.
2) The network link from this machine to the MessageBox is down.
3) The DTC Configuration on either this local machine or the machine hosting this MessageBox is incorrect.

We use BizTalk Deployment Framework (BTDF).  I had copied my binding file and updated in Visual Studio.  This is the second or third time that the XML editor of Visual Studio has bit me; it re-arranges the XML in the binding file, and the binding file import is apparently very picky about the layout.  Not sure why it cannot use standard XML conventions.

The moral of the story is to use NotePad++, NotePad or some other safe editor that doesn’t take any liberties with reformatting the XML. I rebuilt my MSI, redeployed, and it worked fine.

What helped me figure it out was this blog:  http://kundankarma.blogspot.com/2012/12/problem-enlisting-send-port.html.
Sure enough I looked at the SendPorts and they had no filters; i.e. the filters had been lost somehow by the editor issue.  Now why it causes the error “unable to communicate with the Messagebox” is entirely a mystery.