BizTalk 2013 R2 known bugs, issues & quirks

Below a list of know bugs, issues, & other quirks* of BizTalk 2013 R2 (mainly CU3) and Visual Studio 2013 (update 4) , but I will update with fixes as the CUs come out or when I know about a new issue, so if you have another one I will add it (and link to it if you have a blog about it) if you let me know.  This in addition to the ones listed by Microsoft on Known Issues in Installation, Configuration, and Deployment

I’ve now posted the below article on a TechNet wiki

* My definitions for classifying these are
: Causes negative impact and no known work around or requires a lot of effort to work around.
Issue: Causes negative impact but has an easy or quick work around.
Missing: A feature that BizTalk doesn’t have that would make our life easier.
Quirk:  Something strange or unusual but does not cause a negative impact so far as known.


Microsoft BizTalk Mapper (Visual Studio)

Details: If you have an existing element in a schema mapped from to an Element, and you then add an attribute at the same level with the same name, the mapper will change the link to go to the attribute.
Work around: Add the link for the Element back after adding the attribute to the schema and check & correct the attribute link.
Note: The reverse applies as well, if you are coming from an Element and add an attribute of the same name, it will change the link.

Issue: The Use XSL Transform setting has no effect in Visual Studio

Details:  Changing the XSL Transform setting has no effect when you test the map in Visual Studio.  See BizTalk 2013 R2 CU2 & BizTalk 2016 – Use XSL Transform
Work around: Test the maps at run-time.

Quirk: How the Mapper displays items starting with underscore.

Details: If you have a schema where a Element, Attribute or Record that starts with a underscore, it shows in the mapper as ending with a underscore.
QuirkUnderscoreWork around: None
Note: No impact on functionality.

Missing: Replace functoid in map

Details: In earlier versions of Visual Studio you used to be able to drag and drop a functoid from the toolbox onto a functoid on the map to replace it.
Work around: Drop the new functoid next to the existing and drag the connecting lines to the new functoid.
More: This has was set to the status backlog in User Voice Fix Functoid replacement in Visual Studio before the site was shut down.

Missing: Some attributes in the map can’t be edited in the editor

Details: Some attributes in the map cannot be edited in them map properties.  These are
Work around: Open the map in a XML editor and set them manually.
Update: This was raised on User Voice The BizTalk Mapper needs all the custom map attributes exposed in the editor properties before the site was shut down.

BizTalk (schema) Editor (Visual Studio)

Issue: Can’t set decimal precision for a decimal type in the schema editor

Details: There in no option in the Schema Editor to set how many decimal points you want for a decimal type.
Work around: Open it up with the XML Editor or text editor and add it manually. See Base Data Types and Restrictions in the Schema Editor
Note: This has been an issue since 2004, so a long standing issue that applies to earlier version of BizTalk/Visual Studio as well.

Missing: Can’t validate / generate JSON payloads from Visual Studio

Details: It would be good to be able to validate JSON payloads against a schema or to generate JSON messages from a schema like you can with XML and Flat Files.
Work around: Deploy the schemas and pipelines in Development and have the run-time parse the messages.
Update: This was raised on User Voice Visual Studio support for Json Schemas before the site was shut down.

BizTalk Orchestrations

Missing: Can’t create custom Orchestration shapes

Details: There is no ability to create a custom orchestration shape to make code re-usability easier.
Work Around: Copy and past the shape.
Update: Status of Under Review on User Voice Custom Orchestration Shapes before the site was shut down.

Business Activity Monitoring

Missing: Tools to make BAM development easier

Details: Having to use Excel and other clunky tools to develop and maintain BAM definitions.
Work around: None
Update: Was Status of Under Review on User Voice Better support for BAM before the site was shut down.  As the BAM Portal has been deprecated in BizTalk 2020, and more logging to Azure has been implemented, I would think the rest of BAM is going to go the same way.

BizTalk Server Administration (Console)

Issue: HTTP Method and URL Mapping & SOAP Action too small

Details: The HTTP Method and URL Mapping in WCF-WebHttp or SOAP Action header in other WCF adapters in the Transport Properties dialogue windows are too smal and you can’t resize them.
See also Resizeable windows
Work around: Compose the settings elsewhere and paste them in.

Missing: The ability to copy and past a port

Details: It would make development easier sometimes of you could copy and existing port with all it’s settings.
Work around: Export a bindings file and edit the name of the port and re-import.
Update: This is had status Under Review on user voice Copy and paste Ports from the Admin Console before the site was shut down.

Unit Tests

Issue: When you run unit tests it always does a rebuild of the entire solution

Details: When you run the unit test it always does a rebuild of the entire solution, even if you have made no changes or just a change to the unit test.  With a large solution, this can significantly impact how long it takes to do unit tests.
Note: This is not BizTalk specific see Unnecessary project rebuilds when unit testing in Visual Studio
Update: This has been raised on User Voice Prevent rebuild each time a test is run before the site was shut down.


Issue: Redeployment of schema referenced by maps fails (Fixed in CU4?)

Details: Trying to re-deploy a schema that is referenced by a map on a port fails with the following database error.

Removal of the assembly failed. Make sure that all items in the assembly you are trying to remove fulfill the following conditions:
1. Pipelines, maps, and schemas are not being used by Send Ports or Receive Locations in the same or referenced application(s)
2. Roles have no enlisted parties
Database Error:
The DELETE statement conflicted with the REFERENCE constraint “bts_sendport_transform_foreign_transformid”. The conflict occurred in database “BizTalkMgmtDb”, table “dbo.bts_sendport_transform”, column ‘uidTransformGUID’.
The DELETE statement conflicted with the REFERENCE constraint “fk_bt_mapspec_bts_item”. The conflict occurred in database “BizTalkMgmtDb”, table “dbo.bt_MapSpec”, column ‘itemid’.The DELETE statement conflicted with the REFERENCE constraint “bts_sendport_transform_foreign_transformid”. The conflict occurred in database “BizTalkMgmtDb”, table “dbo.bts_sendport_transform”, column ‘uidTransformGUID‘.

Work Around: Remove the maps from the ports that reference the schema and add them back afterwords.
Fix: (supposedly) Deploy CU4, see FIX: Redeployment of schema referenced by maps fails after you install BizTalk Server kb 3167704 in CU4, however I just get a different error now sometimes. Still need to use the workaround in those cases.
Note: This was also fixed earlier in BizTalk 2010 and 2013 see kb 2908686
Update: This was raised on User Voice Remove forced dependancy checks on Schema and Maps like ESB does before the site was shut down.

Issue: If you deploy a MSI without bindings it can revert to an older binding

Details: If you deploy a MSI without bindings or you refresh a DLL and you don’t apply bindings afterwards either automatically or manually as part of the deployment, it can sometimes end up with a previous state of the bindings.
Work Around: Delete all the files from the folder %APPDATA%\Microsoft\BizTalk Server\Deployment\BindingFiles\ before importing the MSI.
Note: This has been issue with previous version of BizTalk as well, see Unexpected bindings reset on BizTalk 2009

Issue: You can’t export the Tracking settings on Policies via bindings file

Details: If you export a bindings file it does not contain the tracking settings for a Policy and there doesn’t seem to be a way to automatically set them.
Note: Raised on StackOverflow How to import/export the tracking setting of a policy
Work Around: Manually set these after deployment


BizTalk Server Administration (Console)

Issue: Export Bindings is grayed out after importing bindings

Details: After deleting all artifacts, redeploying artifacts and then importing binding. Export Bindings is grayed out and unavailable in BizTalk Server Administration.  Refresh does not fix this.
Work around: Close and re-open or open a new BizTalk Server Administration Console

Issue: Restart is grayed out in BizTalk Server Administration

Details: If you have selected multiple hosts in the Host Instances and the last one you host you selected is an isolated host, either at the bottom of the list when selecting with Ctrl + A or Shift + Click, or alternatively the last added by Ctrl + Click, then Restart options is grayed out in the BizTalk Server Administration console
Work around: Either un-select the isolated hosts (Ctrl + Click) or sort the Host Instances so that the last host in the list is not a isolated one.

Missing: The ability to view messages as XML or JSON in the console

Details: In the administration console when you view a tracked message, you can only see it as text or Binary, and not as XML or JSON.
Work around: Save the message to disk and view/format it with your favourite tool
Update: This was set to status Backlog on User Voice XML / JSON Viewer before the site was shut down.

Missing: No Audit logs

Details: There is no audit trail in the BizTalk Administration console for such things as when a Port or Host Instance was stopped, (re)started and why (error or console) or by whom. Also when an what version of a DLL was imported into the BizTalk database.  Details of when certain events occurred could help to diagnose issues.  See Enable – Disable ports history in BizTalk
Work around: Use of external tools to track changes
Update: This was raised on User Voice User Auditing of Administration Events before the site was shut down.
Update 2: This was released as a feature for BizTalk 2020

Issue: Time out in admin console for Tracked message events or Instances

Details: Sometimes when you do a search in the Admin console for tracked message or instances it will time out.
Work arounds: Use URI rather than port name. Reduce the Maximum matches. Set Creation Time greater than a datetime.

ESB Exception Portal

Issue: ESB.AlertService.QueueGenerator.ProcessFaultsForQueue – Cannot interpret token ‘!’ at position 62

Details: This is caused when in the ESB Exception Portal you add a Alert rule that contains a not condition and it creates it with a != rather than a <>
Work around:  Run the following SQL with dbo priviliges

use [EsbExceptionDb]
update [AlertCondition] 
set Operator = '<>'
where Operator = '!='
update [Alert] 
set ConditionsString = Replace(ConditionsString,'!=','<>')
where ConditionsString like '%!=%'

Fix: Edit the following .aspx pages
ESB.Portal\Alerts\ConditionAdd.ascx & AlertEdit.aspx
Change != to <>

Issue: ESB Exception Notification keeps sending THE same alert

Details: This is caused by an alert subscription which has an invalid email address. This means the emailalert is not successfully sent and not marked as sent.

Workaround: Run the following SQL and make sure to remove the offending subscription from the alert.

update [EsbExceptionDb].[dbo].[AlertEmail]
set sent = 1
where sent = 0
and [To] = 'offendingemail'


Subscription Filters

Missing: The ability to do more complex subscription filters.

Details: You can only do a single level of logic e.g. (A and B) or (A and C) rather than A and (B or C).
Work around: None
Update: This was been raised on User Voice Enhance the subscription filters before the site was shut down.

WCF-WebHttp adapter

WCF-WebHttp Adapter – Basic Authorisation does not work

Details: If you try and configure the WCF-WebHttp adapter to use basic authentication it does not pass the Authorization header
More: See WCF-WebHttp Adapter – Basic Authorisation. This appears to happen when the API does not return a list of allowed authentication schemas.
Work arounds: Either put the authorization in the outbound HTTP headers in the Message tab (not recommended), create a custom behaviour to add it, or use the old HTTP adapter.

Bug: BizTalk WCF-WebHttp adapter does not detect 500 error & http  StatusCode not available for other errors codes (fixed in CU5)

Details: When you get a 500 error from a RESTful service using the WCF-WebHttp adapter it behave differently from other non 200 HTTP status codes.
For other error codes it throws a fault exception with the response payload including the payload returned.  This makes it hard to handle 404 errors  in a messaging only solution
See BizTalk WCF-WebHttp adapter does not detect 500 error for more details. Work around: As a work around you could develop orchestrations to check for the WCF.InboundHttpStatusCode ContextProperty and its value and catch the other errors in a System.Exception block* (see bug below)
Fix: The fix for the 500 not throwing an error is included in CU5

Bug: BizTalk WCF-WebHttp adapter does not set the message type on error

Details: When you get a non 200 series http status code from a RESTful service using the WCF-WebHttp adapter, the SOAP fault message published to the message box does not have the context property MessageType.  This means you cannot map it or catch it in a Fault on the Logical Port in the Orchestration
Work around: Catch it in a System.Exception block in the Orchestration, see (BizTalk 2013 R2 JSON Encoder error – “Object reference not set to an instance of an object” – Part 1) or use BRE rules in a Pipeline to handle the SOAP Exception see BizTalk 2013 R2 JSON Encoder error – “Object reference not set to an instance of an object” – Part 2

Bug: BizTalk WCF-WebHttp adapter does not set http status code on error

Details: When you consume a RESTful service and get a non 200 series status code back, it will throw a SOAP exception in the Adapter (apart from the 500 status as above) and not promote the http status code in the message context InboundHttpStatusCode or InboundHttpStatusDescription like it does for a successful ones.  If these were in the Context Properties it would make handling exceptions easier.
Work around: Have to inspect the text in the System.Exception message to work out what exception was thrown

Missing: BizTalk WCF-WebHttp adapter ability to suppress 404 status code

Details: When you do a get on a RESTful service and get a 404 status code and a payload saying that the object you asked for does not exists, it will throw a SOAP exception.  It would be nice to be able to suppress a 404 status code (or other status codes) on a GET (or other operations) and to parse the response as normal through the pipeline and process as business exception rather than a System Exception.
Work around: Catch the exception in an Orchestration and look for the not found error description that the service threw.

WCF-SQL adapter

Bug: SQL Polling: Receive Location polling data after service window stop time

Details: If you Enable service window on a WCF-SQL port it can sometimes poll outside of that window.  See Stackoverflow: Receive Location polling data after service window stop time
Work around: None know.
Note: Occurred in BizTalk 2013 R2 CU1

File Adapter

Missing: Cannot configure the file adapter to limit the rate of pickups.

Details: Cannot configure the file adapter to limit the rate at which it picks up files.  This can cause throttling issues in BizTalk
Work around: Write your own file pickup adapter
Update: This was raised on User Voice Pickup limits for File Adapter before the site was shut down.

Missing: Ability to be able to pick up empty files

Details: The file adapter will discard zero length files.  Sometimes clients do want BizTalk to process these and send a message to the destination system. The other adapters do not have this limitation.
Work around: Use the FTP adapter instead.
Update: This was raised on User Voice FILE adapter support for empty files and had the  status of Backlog before the site was shut down.

SFTP Adapter

Bug: SFTP Receive Location will stop picking up files

Details: A SFTP Receive Location will stop picking up files with no errors or warning.  Only restarting the Host Instance that it is running in will then have it pick up the files
More Details: Technet Forum Biztalk SFTP Adapter Issue in Receive Location.  For BizTalk 2016 possibly the same issue was fixed, FIX: SFTP adapter receive locations stop working intermittently during higher load in BizTalk Server

Missing: Cannot configure SFTP for read only files.

Details: There is no option like Delete After Download = No and Enable Timestamp comparison like the FTP Adapter.  See Microsoft BizTalk Server 2013 R2 SFTP Adapter Tricks and Pitfalls – The Messaging Engine failed while notifying an adapter of its configuration
Work around: Install a third party adapter that does have this option.
Update: This was raised on User Voice Enable timestamp comparison on sftp adapter, before the site was shut down.
Note: This was resolved in KB 4464664 but only for BizTalk 2016 in CU6

Missing: Cannot configure SFTP to use temporary file names

Details: There is no option to use “Use temporary file while writing” or “Rename files while reading” like the file adapter for the SFTP adapter nor a After Put like the FTP adapter to rename the file.  This can lead to issues with partially written files being picked up
Work Around: Use the Temporary Folder option

Missing: Cannot configure SFTP adapter to use SSO

Details: There is no option to configure the SFTP adapter to use SSO use detailed in BizTalk SSO & SSO Affiliate Settings
Update: This has was marked as status in progress on User Voice SSO Affiliate Applications support for native SFTP adapter, also Wider support for SSO for out-of-the-box Adapters before the site was shut down.
Note: This was released as a feature for BizTalk 2020

FTP Adapter

Missing: Can’t configure receive locations to the same URI using different credentials

Details: You can’t configure multiple receive locations going to the same FTP sever and path, even though they use different credentials means they are mapped to different folders.
Update: This was raised on user voice FTP adapter should use account name or SSO Affiliate Application Name to distinguish receive locations and was sitting at status Backlog, before the site was shut down.

Pipeline components

Issue: Changing the TargetCharset in the XML or Flat File assembler has no effect in the BizTalk Administration Console

Details: If you change the TargetCharset value in a pipeline via the BizTalk Administration console it does not change the outgoing payload to that encoding. See Flat File Assembler Encoding and Charset
Work Around: Change the Encoding in Visual Studio and redeploy the pipeline.
Note: This has been an issue since BizTalk 2006, see BUG: The TargetCharset value in an XMLTransmit pipeline configuration may not take effect as expected in BizTalk Server 2006
Was raised on User Voice Fix the long time BUG regarding XMLTransmit pipeline and targetcharset before the site was shut down.

Issue: The ESB Add Namespace pipeline component adds the BOM back

Details: If you use the ESB Remove Namespace pipeline component and tell it RemoveByteOrderMark and follow it with a ESB Add Namespace Pipeline component in a send pipeline to a file, then the file produced will have a byte order mark.
Work around: Use a custom add namespace pipeline component.

Bug: The BizTalk JSON Encoder hangs forever

Details: A  XML schema that references a complex type or another schema will cause the JSON Encoder to Hang.
Work around: Simplify the schemas you use to create JSON payloads.
More Details: Mark Brimble’s blog post JSON Encoder hangs forever

Issue: The BizTalk JSON Encoder applies same type to elements with the same name

Details: If you have elements at more than one level of your XML schema with the same name, but different types, then it will apply the same type as per the first one it encounters.  This will either cause things to be quoted when they should not be, or if it is a string that it thinks is a int etc. it will throw the following exception if the string cannot be an int.
“There was a failure executing the send pipeline <pipeline & URI details> Reason: Input string was not in a correct format. “
Work around: Rename the fields so they are unique.
More Details: Pim Simons blog post JSON Encoder Type Bug who found it in BizTalk 2016.  A similar issue has also been raised on Fix bug in JsonEncoder – cannot handle records and fields with the same name.

Issue: The BizTalk JSON Decoder drops trailing 0’s after the decimal

Details: If you use the JSON Decoder and you have a decimal element it will drop trailing zeroes after the decimal point. E.g. -10.00 becomes -10.  If there are non zeroes it will leave it alone e.g. 10.41 stays 10.42
Work Around: In a map use a scripting functoid and format it back to the number of decimal places required Return parameter.ToString(“F2”);
 this work around will format it to two decimal places even if there are more, so please ensure you format to the appropriate number of places.
Update: This could possibly be resolved by Microsoft updating the version of Newtonsoft as per User Voice Json Encoder/Decoder use new version of Newtonsoft.Json before the site was shut down.
Note: This was implemented in BizTalk 2016 with some CU’s.
However  It has been reported on Twitter that “We have some issues with the new #biztalk CU7. The json encoder has started formatting boolean values as string values, like “true” instead of true.” and “As we wanted the FTP fixes in CU7 we installed it anyway and replaced the jsonextension dll with an older version.”

Issue: The BizTalk JSON Encoder outputs a Integer as a decimal

Details: If you use the JSON Encoder and have a element defined as Integer, when it goes through the JSON Encode it becomes a decimal, e.g. 100 becomes 100.0
Work Around: Change the type from Integer to Int or Long depending on the size of the expected number (if unbound, use long).

Issue: The BizTalk JSON Encoder adds a time to a Date

Details: If you use the JSON Encoder and have a element defined as Date, when it goes through the JSON Encoder it becomes a datetime, e.g. 1999-05-31 becomes “1999-05-31T00:00:00”
Work Around: Change the type to string.

Issue: The BizTalk JSON Encoder changes blanks in XML to null in JSON

Details: If you use the JSON Encoder and have a element that is empty, it becomes a null in the JSON payload.
More Details: REST JSON Christmas Puzzle
Work Around: Use the BRE Pipeline and do a Replace the string “: null in the message body with the string “:”” (initial concept from REST JSON Christmas Puzzle – Work around).
Note: The above work around has an unintended side effect that it causes a BOM to be added. This may cause issues with some systems.

Quirk: The BizTalk JSON Encoder changing date-time timezone

Details: If you use the JSON Encode and have a element defined as a datetime, when it goes through the JSON Encoder it change it to local times. e.g. in 1999-05-31T13:20:00.000-05:00 becomes “1999-06-01T06:20:00+12:00”.
Work Around: Change the type to string.
Note: As the time is still actually the same actual time, classifying as a quirk.

Quirk: The BizTalk JSON Encoder – JSON Array

Details: JSON Encoder not creating JSON Array for what should be a repeating element.  This occurs if you don’t have schema deployed that matches the XML payload and there is only a single item. See JSON Array –
BizTalk JSON Encoder|

Work Around: The XML must conform to a schema that BizTalk knows about. Use a custom send pipeline that contains a XML Assembler pipeline component before the JSON encoder pipeline component.

Quirk: The BizTalk JSON Decoder changing date-time timezone

Description: If you use the JSON Decoder it will cast ISO formatted dates to the local time zone, See BizTalk JSON Decoder changing date-time timezone
Work Around: None
: As the time is still actually the same actual time, classifying as a quirk.

Missing: Ability to use XSLT 2.0 or 3.0 in BizTalk Maps

Description: You can’t use XSLT 2.0 or 3.0 in BizTalk Maps.  This is actually a limitation of .Net.
Work Around: Use a third party component like Saxon as described here  Is there XSLT 2.0 or 3.0 support in BizTalk Server 2016 mapping?
Update: This feature has been requested on User Voice Support for XSLT2 or XSLT3 before the site was shut down and is marked requested by other team (.Net), and also on Github for dotnet
Update 2: This was released as a feature in BizTalk 2020.


Author: Coen (Colin) Dijkgraaf

A Integration Consultant for Datacom in Auckland, New Zealand, working mainly with BizTalk and Azure. You can follow me on Twitter, StackOverflow and WordPress

6 thoughts on “BizTalk 2013 R2 known bugs, issues & quirks”

  1. Hi Colin,

    Recently, I found in BizTalk 2013 environment, as long as the server has CU2 installed, you would have the redeployment issue (REDEPLOYMENT OF SCHEMA REFERENCED BY MAPS FAILS) mentioned in your post, which Microsoft claims fixed in CU3. But it does not seem work even CU4 is applied.

    The only solution to make it work is, if you have CU2 installed and any latest CUs installed, uninstall CU2 and all the installed CUs after CU2, then restart server, install only the latest CU only. Just uninstall CU2 and leave CU3 and/or CU4 on the server would not work.

    I have contacted Microsoft for this issue. Will update here if I receive any update.

  2. Another bug for BizTalk 2013 R2 has been confirmed by Microsoft BizTalk Product Group. The bug is in HL7 accelerator to process messages in FIFO. The RTM version of BizTalk 2013 R2 is working fine. As long as any CU installed, the MLLP adapter at send port will have a different Ack code options than RTM. In RTM there were an option called All Ack Codes has been replaced by “AA, CA, AR, CR, AE, CE” and “CUSTOM” option. Microsoft has confirmed that if “AA, CA, AR, CR, AE, CE” is selected with order delivery turned on at send port, if there is no ack returned from downstream system, after retry fails, the next message will get sent out. The walkaround is using “CUSTOM” and manually typed ack codes “AA, CA, AR, CR, AE, CE”. This issue only exists with any existing 4 CUs installed on top of RTM.

Leave a Reply

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

You are commenting using your 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 )

Connecting to %s

This site uses Akismet to reduce spam. Learn how your comment data is processed.

Mike the Tester

A blog about all things testing. Views are my own

Nick's Blog

Biztalk gotcha!



A Different Kind of Query

Technology, music, life, and musings

Vierodan IT Space

Spread up technology

BizTalk Server Help book!

Made easy and simple


Blog on BizTalk Server

Blog Of the Serverless Spirit

Stray Notions on All Things Microsoft Azure and BizTalk

Microsoft Azure/BizTalk_Read

Let's learn and share !

Boutaleb Hicham

Biztalk & Azure Integration Architect : Logic Apps, Serverless, Azure Service Bus, BizTalk Server, and Hybrid Integration

Pieter Vandenheede

Stories, tips & tricks for BizTalk Server, Azure, Data Science & Machine Learning

Glenn Colpaert

Blogging with my head in the (Hybrid) Cloud and my feet on premises! Azure / IoT / Integration


BizTalk blog by Knut Urke

Dragon's BizTalk Blog

A blog about BizTalk, and other integration tools.

The Deployment Bunny

OS Deployment, Virtualization, Microsoft based Infrastructure...

Integration Made Easy

Demystify Integration Development

%d bloggers like this: