Troubleshooting Pipelines

Problems with pipelines can usually be traced back to issues with the configuration of individual components or, for custom-built components, specific programming logic. This section offers advice on how to identify and resolve common pipeline issues.

The BizTalk Server SDK ships with the following command-line tools you can use to troubleshoot your pipeline components:

  • DSDump.exe. Enables you to dump the document schema structure. This tool can be helpful when you get parsing engine errors such as $Root$0$3$2 and you need to decode them. Numbers after $ mean 0-based index or records as they appear in the document schema.
  • FFAsm.exe. Runs the flat file assembler component, directly invoking it by emulating a send pipeline.
  • FFDasm.exe. Runs the flat file disassembler component, directly invoking it by emulating a receive pipeline.
  • Pipeline.exe. Runs a send or receive pipeline; accepts one or more input documents and their parts, XSD schemas, and related information; and produces an output document after the pipeline runs. Pipeline.exe does not access BizTalk Server databases, so pipelines containing BizTalk Framework assembler and disassembler components that access BizTalk Server 2006 databases during execution may not be supported.
  • XMLAsm.exe. Runs the XML assembler component, directly invoking it by emulating a send pipeline.
  • XMLDasm.exe. Runs the XML disassembler component, directly invoking it by emulating a receive pipeline.

These can be found in the <Installation Path>\SDK\Utilities\PipelineTools directory of BizTalk Server. For more information about the pipeline tools, see Pipeline Tools.

This section contains a set of questions and answers designed to help you resolve pipeline issues.

Why is my custom policy file generating strange errors?

If you are using a custom policy file, you may encounter the following errors when compiling your solution:

  • Stage should contain at least <n> components
  • Identifier expected

The first problem occurs when the number of components required per stage is less than the number of components in the stage. The second problem occurs when the execution mode value defined for some stage in the policy file is None; only FirstMatch and All are allowed.

To fix these errors, you must edit your custom policy file to include the proper values. For example, in the configuration below the number of components per stage must be adjusted:

<?xml version="1.0" encoding="utf-8"?>
<Document xmlns:xsd="" xmlns:xsi="" CategoryId="" FriendlyName="">
    <Stage Name="Decode" minOccurs="5" maxOccurs="10" execMethod="All"></Stage>

The Stage element attribute minOccurs must be changed to "1" as shown below.

<?xml version="1.0" encoding="utf-8"?>
<Document xmlns:xsd="" xmlns:xsi="" CategoryId="" FriendlyName="">
    <Stage Name="Decode" minOccurs="1" maxOccurs="10" execMethod="All"></Stage>

Why am I losing data when using my custom disassembler pipeline component?

Did you close the incoming data stream?

When you write custom disassembler code for pipeline components in BizTalk Server 2006, ensure that you do not close the incoming data stream in the disassembler code. The incoming stream from the input message is a shared resource and is used by the message-body tracking component in the BizTalk Server 2006 Messaging engine.

If you either implicitly or explicitly close the incoming stream, tracking data may be lost and you will be unable to examine the stream data in the Health and Activity Tracking (HAT) tool in BizTalk Server 2006.

Why am I receiving parsing and validation errors in my receive pipeline when using my custom disassembler pipeline component?

When writing a custom disassembler pipeline component you should always:

  • Read from the incoming data stream until no more bytes are read.
  • Reset the data stream pointer to the start of the stream.

Failure to read all of the data in the incoming data stream could cause your component to process the data incorrectly or miss important data. If you fail to reset the data stream pointer, the next component in the pipeline receives what appears to be an empty (or incomplete) stream.

For example, this code illustrates logic to use the Seek method to point to the beginning of the stream before returning the stream:

myDataStream.Seek(0, SeekOrigin.Begin);
return myDataStream; 

How do I use a signing certificate in outgoing messages?

You apply a signing certificate to an outgoing message by adding an encoding component (S/MIME) in the send pipeline. After the component has been added, you configure the component to sign all outgoing messages by clicking True for the Add signing certification to message property. The signing certificate that is used to sign the outgoing message is retrieved from the personal certificate store for the host service account where the pipeline is running.

BizTalk Server supports only one personal certificate for each BizTalk group. A BizTalk group can represent an enterprise, a department, a hub, or another business unit. The personal certificate that is used by the BizTalk group is specified by setting the thumbprint of the personal certificate in the BizTalk group properties.

To enter a thumbprint for the personal certificate for the host service account that is running the pipeline
  1. Start BizTalk Server Administration.

  2. Right-click the BizTalk group that you want, click Properties, and then click Certificates.

  3. In the Thumbprint box, type the thumbprint of the private key certificate that is used to digitally sign outgoing messages from this group. The certificate thumbprint has the following format (where H is a hexadecimal digit):


  4. Click OK.

For a demonstration of signing outgoing messages, see MIME (BizTalk Server Sample).

My message has promoted properties. Why isn't it being routed?

To route messages based on promoted properties or to use promoted properties in any part of your BizTalk Server application, you must use a pipeline that actually promotes properties as specified in the promoted property schema. Unless you have a custom pipeline that promotes properties and performs other custom work, you will need to specify the XMLReceive pipeline in your receive location.

When creating a receive location, PassthruReceive is the default pipeline. You must manually change this to XMLReceive pipeline.