BizTalk Host Integration Server Build Errors, Debugging, and Deployment Fixes
Why This Is Happening
I've seen this exact situation play out on dozens of enterprise floors: a developer or DBA fires up a BizTalk Host Integration Server deployment, everything looks fine on the surface , adapter configured, schemas compiled, orchestration bound , and then the pipeline explodes at runtime with a cryptic DB2 connectivity error, a package binding failure, or a DRDA protocol mismatch that makes absolutely no sense at first glance. The build log is three pages of noise and the actual cause is buried somewhere in line 847.
Here's the honest reality. BizTalk Host Integration Server (HIS) sits at one of the most complex intersections in Microsoft's enterprise stack: it bridges modern Windows infrastructure to legacy IBM mainframe systems, AS/400 boxes, and DB2 Universal Database environments using protocols that predate most of the developers working with them. DRDA, SNA LU6.2, APPC, these aren't technologies most people learn in school anymore. So when something breaks, the error messages are almost never helpful. You get E_FAIL (0x80004005) or DB2OLEDB_ERR_EXECUTE_ERROR and you're left guessing.
The most common culprits behind BizTalk HIS build errors and deployment failures fall into a few buckets. First, OLE DB Provider for DB2 data source misconfiguration, specifically wrong Network Transport Library selection (SNA vs. TCP/IP) or mismatched APPC mode names that don't align between the SNA Server configuration and the actual host. Second, authentication failures caused by case-sensitivity differences between DB2 platforms, AS/400 demands UPPER CASE credentials, DB2 UDB for Windows NT stores passwords in mixed case, and sending lowercase to the wrong system causes silent auth rejections. Third, package binding failures where the DRDA COLLECTION you specified either doesn't exist or the connecting user lacks BIND authority. Fourth, isolation level mismatches between what your BizTalk orchestration expects and what the DB2 host is actually enforcing.
What makes this especially painful is that BizTalk Server's event log entries rarely point you directly at the HIS layer, they bubble up as adapter exceptions that look like generic transport errors. You have to know to dig into the HIS-specific event sources and the OLE DB Data Link configuration to find the real problem.
I know this is frustrating, especially when it blocks an integration that an entire business workflow depends on. The good news is that 90% of BizTalk HIS deployment failures trace back to a handful of fixable configuration gaps. Browse all Microsoft fix guides →
The Quick Fix, Try This First
Before you touch a single registry key or rebuild a package, open your UDL (Universal Data Link) file and run the Test Connection from the Data Link Properties dialog. This one step eliminates or confirms the OLE DB layer as your problem in under two minutes, and it saves you from chasing BizTalk adapter logs when the real issue is a misconfigured data source sitting underneath everything.
Here's exactly how to do it. Navigate to your UDL file location. If you're using the SNA Server program folder entry point, the file lives at:
%ProgramFiles%\Common Files\System\OLE DB\Data\Right-click your .udl file and open it with Notepad first. Confirm these four things before you even open the Data Link Properties dialog:
- The Provider line reads
MSDASQLor explicitly namesDB2OLEDB, not a generic OLE DB provider that accidentally got selected. - The Network Transport Library is set correctly: if you're on TCP/IP, you need a valid Network Address and port (default DRDA port is 446). If you're on SNA LU6.2, you need valid APPC Local LU Alias, APPC Mode Name, and APPC Remote LU Alias values, all three, not two of three.
- Your Initial Catalog value matches the correct term for your DB2 platform: it's called LOCATION on DB2 for MVS/OS/390, RDBNAM on DB2/400, and DATABASE on DB2 Universal Database. Getting this wrong is surprisingly common when someone copies a UDL from one environment to another.
- Your credentials are in the right case for the target platform. AS/400 only accepts UPPER CASE. If your username contains any lowercase letters, change them now.
Now open the Data Link Properties, go to the Connection tab, fill in your credentials, and click Test Connection. A successful test here means your OLE DB Provider for DB2 layer is healthy and you can move up to the BizTalk adapter level. A failure here, and you've just found your real problem before wasting hours in BizTalk Server admin tools.
The first thing that breaks BizTalk Host Integration Server deployments is the wrong OLE DB provider getting selected during initial setup, often because someone configured the UDL on a machine that had multiple providers installed and accidentally chose the wrong one from the dropdown.
Open Data Link Properties by double-clicking your UDL file. Go to the Provider tab. You should see OLE DB Provider for DB2 selected. If you see anything else, Microsoft OLE DB Provider for ODBC Drivers, Microsoft OLE DB Provider for SQL Server, anything other than the DB2-specific provider, that's your problem right there.
Select OLE DB Provider for DB2 and click Next to move to the Connection tab. Now fill in the Data Source field. This field is optional in general usage but becomes required when you're loading the configuration from the SNA Server program folder, and in BizTalk HIS deployments, it's always best practice to populate it. This value also becomes the filename for your UDL file stored in:
%ProgramFiles%\Common Files\System\OLE DB\Data\Give it a meaningful name that identifies the target system, something like DB2_AS400_PROD or DB2_MVS_FINANCE. This naming discipline matters when you have multiple data sources and need to troubleshoot which UDL a failing BizTalk adapter is actually reading.
If the Test Connection button becomes available and returns a green success message at this stage, your provider selection is correct and you can move to credential verification. If you get error 0x80004005 or a provider-not-found message, the OLE DB Provider for DB2 may not be properly installed, check Add/Remove Programs for the Host Integration Server client components.
Authentication failures in BizTalk HIS deployments are almost always a case-sensitivity problem, and the error messages almost never tell you that explicitly. You'll see something like SQL30082N SECURITY PROCESSING FAILED or a generic OLE DB error 0x80040E4D and assume it's a wrong password. Sometimes it is. But often, it's the right password in the wrong case.
Here's the breakdown by DB2 platform:
AS/400 (DB2/400): The system is case-sensitive and it only accepts user IDs and passwords in UPPER CASE. The OLE DB Provider for DB2 is actually smart enough to handle this, if your DB2/400 connection fails with an authentication error, the provider will automatically retry by forcing both the user ID and password into UPPER CASE. But if you're persisting credentials in the UDL and they're stored in mixed case, you'll hit a first-attempt failure every connection, which can manifest as intermittent BizTalk adapter timeouts under load.
Mainframe (DB2 for MVS/OS/390): The mainframe is case-insensitive. The provider sends credentials in UPPER CASE regardless of what you enter, so this platform rarely causes case-related auth headaches.
DB2 UDB for Windows NT: This is where people get burned. The user ID is stored in UPPER CASE, but the password is stored in mixed case. The provider sends the password exactly as entered, no auto-correction, no retry. You must enter the password in the exact case it was set. Also important: you don't need to qualify the Windows NT username with the domain name.
In the Connection tab of Data Link Properties, enter your credentials, then use the Test Connection button to verify. If auth succeeds interactively but fails in BizTalk at runtime, check whether the BizTalk Host service account has permissions to read the UDL file and whether the saved credentials in the UDL are still valid.
This step resolves the majority of BizTalk Host Integration Server build errors related to DRDA connectivity. The Network Transport Library property determines whether your connection goes over SNA LU6.2 or TCP/IP, and choosing the wrong one, or choosing the right one but omitting required dependent properties, will fail silently in ways that are hard to trace.
In the All tab of Data Link Properties, find the Network Transport Library property. The default value is SNA. If you're connecting over TCP/IP (which is the modern standard for most deployments), change this to TCP/IP.
When TCP/IP is selected, these two properties become mandatory:
- Network Address: The TCP/IP address or hostname of the target DB2 system. This can be an IPv4 address like
192.168.10.45or a resolvable hostname. If you're using a hostname, confirm it resolves correctly from the BizTalk server before blaming HIS. - Network Port: Default is 446, which is the well-known DRDA port. Some organizations run DB2 on non-standard ports, verify with your mainframe or AS/400 administrator.
When SNA is selected instead, these three properties become mandatory:
APPC Local LU Alias → Configured in SNA Server (local side)
APPC Mode Name → Must match host config (e.g., QPCSUPP, #INTER, #BATCH)
APPC Remote LU Alias → Configured in SNA Server (remote/host side)Legal APPC Mode Name values are: QPCSUPP (common system default), #INTER (interactive), #INTERSC (interactive with minimal routing security), #BATCH (batch), #BATCHSC (batch with minimal routing security), and #IBMRDB (DB2 remote database access). Using the wrong mode name for your workload type causes session negotiation failures that look like connectivity timeouts in BizTalk event logs.
One of the most confusing aspects of BizTalk Host Integration Server configuration is that the same logical concept, "which database am I connecting to", has a different name depending on which DB2 platform you're targeting. Getting this wrong means your OLE DB connection succeeds but your queries fail because the provider is looking in the wrong place for catalog information.
In the Connection tab, the Initial Catalog field maps to different things on different platforms:
- DB2 for MVS/OS/390: This is the LOCATION. You can find the correct value by asking your mainframe administrator to look it up in the TSO Clist
DSNTINSTunder the DDF definitions section, specifically theDSNTIPRpanel in the DB2 installation manual. Don't guess this value, the LOCATION string must match exactly what's registered inSYSIBM.LOCATIONS. - DB2/400 (AS/400): This is the RDBNAM. Have your AS/400 administrator run
WRKRDBDIREfrom the OS/400 console to list available relational database directory entries. If no RDBNAM exists for your target system, one can be created using the Add option in that same command. - DB2 Universal Database: This is simply the DATABASE name. This is the most straightforward of the three.
The Default Schema property in the All tab is equally important and often overlooked. The OLE DB provider uses this value to scope catalog queries, when BizTalk or any OLE DB consumer asks for a table list via IDBSchemaRowset DBSCHEMA_TABLES, the provider filters results to this schema. It also gets used to build SQL SELECT statements for IOpenRowset::OpenRowset calls. If your Default Schema is blank or wrong, BizTalk adapters that enumerate tables at design time will return empty results or pull from the wrong schema.
Set Default Schema to the DB2 collection name where your target tables live. In most cases this is the same value you'd use for Package Collection.
If your BizTalk Host Integration Server connection tests successfully but your actual data operations fail with errors like SQL0805N Package not found or SQLCODE -818, you have a package binding problem. This is one of the more intimidating errors because it involves concepts from the DB2 side that .NET and BizTalk developers often haven't encountered before.
The OLE DB Provider for DB2 uses DRDA packages stored on the DB2 host to execute SQL statements. These packages need to be bound (created) in a specific DB2 COLLECTION on the host system. In the All tab of Data Link Properties, the Package Collection property specifies which DRDA COLLECTION the provider will use to store and bind these packages.
To fix package binding failures:
- Confirm with your DB2 DBA that the COLLECTION named in Package Collection actually exists on the host.
- Verify that the connecting user has
BINDandEXECUTEauthority on that COLLECTION. Missing EXECUTE authority causes the packages to exist but all queries to fail. - If the packages need to be rebound (common after DB2 host upgrades or after a HIS version upgrade), you may need to drop the existing packages from the COLLECTION and let the provider recreate them on first connection.
Isolation level mismatches show up as SQL0911N (deadlock or timeout) or unexpected rollback behavior. In the All tab, set Default Isolation Level to match what your BizTalk orchestration expects:
CS → Cursor Stability (COMMIT(*CS) on DB2/400 / Read Committed in ANSI)
NC → No Commit (COMMIT(*NONE) on DB2/400, default)
UR → Uncommitted Read (COMMIT(*CHG) on DB2/400)
RS → Read Stability (COMMIT(*ALL) on DB2/400 / Repeatable Read in ANSI)
RR → Repeatable Read (COMMIT(*RR) on DB2/400 / Serializable in ANSI)For BizTalk receive adapters doing read-only data pulls, NC or UR is typically appropriate and gives best performance. For two-phase commit scenarios in BizTalk orchestrations, you need at minimum CS.
Advanced Troubleshooting
When the standard configuration fixes don't resolve your BizTalk Host Integration Server build errors, it's time to go deeper. These techniques are what separate a three-day outage from a three-hour one.
Event Viewer Analysis. BizTalk and HIS write to separate event log sources. In Event Viewer, check both Application and System logs, but specifically filter for these sources: BizTalk Server, DB2OLEDB, and SNABASE. The DB2OLEDB source will log the actual DRDA protocol errors that the BizTalk layer abstracts away. Common event IDs to look for: Event ID 1061 (APPC session allocation failure), Event ID 230 (package not found on remote system), Event ID 1175 (authentication failure with DB2 reason code). These event IDs give you actionable DB2 SQLCODE values to take to your mainframe DBA.
Auto Commit Mode behavior. BizTalk orchestrations that make multiple DB2 calls within a single scope often behave unexpectedly when Auto Commit Mode is enabled (which is the default, it's set to True in the All tab). In Auto Commit Mode, every individual SQL statement is its own transaction and commits immediately. No ROLLBACK is possible. If your BizTalk orchestration relies on transactional atomicity across multiple DB2 operations, you must disable Auto Commit Mode and manage commits explicitly. Leaving the default True in place while expecting rollback capability is a logic error that produces data integrity issues, not runtime exceptions, making it especially hard to diagnose.
Cache Authentication and security. The Cache Authentication property in the All tab controls whether the provider caches sensitive auth information in an internal cache. It defaults to False. In enterprise BizTalk deployments, enabling this can improve connection performance but introduces a security consideration, cached credentials survive process restarts. More importantly, if passwords are rotated on the DB2 side (common in regulated environments), BizTalk will continue using the cached old password until the cache is flushed. Keep this False in environments with password rotation policies.
Host CCSID mismatches. Binary data corruption in BizTalk message payloads from DB2 sources is almost always a Host CCSID problem. The Host CCSID property in the All tab must match the character code set identifier of the data on the remote DB2 system. The default is 37 (US/Canada EBCDIC). If your DB2 system uses a different CCSID, common in non-English-language installations, mismatched CCSID produces garbled strings that pass schema validation but contain wrong data. Ask your mainframe administrator for the CCSID of the DB2 subsystem. Also, if you need to process binary columns as character data, the Process Binary as Character extended property must be set.
Extended Properties for advanced scenarios. The Extended Properties field in the All tab accepts semicolon-delimited additional properties that pass through to the underlying network client. This is the escape hatch for non-standard configurations. Properties set here are interpreted by the provider's network client layer, useful for things like setting alternate TP names when connecting to SQL/DS (DB2/VM or DB2/VSE). The Alternate TP Name property is only required for SQL/DS connections and represents the remote transaction program identifier.
0x08640000 (session limit reached at the host), those require SNA Server-level investigation that goes beyond UDL configuration. Open a support case at Microsoft Support and have your HIS version number, SNA Server topology diagram, and Event Viewer exports ready before calling.
Prevention & Best Practices
BizTalk Host Integration Server deployments fail on a predictable schedule when organizations skip the discipline of documenting their data source configurations. I've watched the same team hit the same DRDA package error six months apart because nobody wrote down what they changed the first time. Here's how to build the configuration hygiene that prevents repeat incidents.
Version-control your UDL files. UDL files are plain text. Put them in source control alongside your BizTalk application artifacts. When a deployment fails in production but works in staging, a diff of the UDL files from each environment tells you in ten seconds what's different. Without this, you're comparing properties one by one across the All tab's property grid.
Document your DB2 platform specifics per environment. Create a one-page reference for each environment that captures: DB2 platform type (MVS/400/UDB), Initial Catalog terminology and value, CCSID, Package Collection name, Default Schema, Network Transport Library choice, and the APPC Mode Name if using SNA transport. This document saves the next engineer who touches this integration from spending half a day rediscovering platform-specific terminology differences.
Test connections after every infrastructure change. AS/400 firmware updates, DB2 maintenance windows, network changes, any of these can invalidate a working DRDA connection. Build a scheduled task or BizTalk Health Monitor rule that runs a connection test against each DB2 data source daily. Catching a broken connection at 2 AM during a maintenance window is much better than catching it at 9 AM when the business is trying to run payroll.
Never save passwords in UDL files for production. The Data Link Properties dialog has an "Allow saving password" checkbox. In production environments, this stores credentials in plain text inside the UDL file. Instead, use Windows Credential Manager or a secrets management solution and configure your BizTalk host service account with appropriate DB2 permissions. The convenience of saved passwords is not worth the security exposure in regulated environments.
- Run Test Connection from Data Link Properties before every BizTalk deployment, five seconds that saves hours of adapter log hunting
- Store UDL files in source control with environment-specific config values separated out as build-time substitutions
- Create a DB2 DBA contact card and pin it to your team wiki, you will need their help with COLLECTION permissions and RDBNAM values
- Set up Windows Event Log forwarding for
DB2OLEDBandSNABASEsources to your monitoring platform so DRDA errors generate alerts before users report failures
Frequently Asked Questions
Why does my BizTalk Host Integration Server connection work in testing but fail in production?
This is almost always an environment-specific configuration difference in the UDL file or the SNA Server configuration. The most common culprits are: a different DB2 LOCATION/RDBNAM/DATABASE value between environments, different APPC LU aliases pointing to different host systems, or credential case issues where the production DB2 instance enforces stricter authentication than the test system. Do a side-by-side comparison of the UDL files from both environments, specifically compare every property in the All tab, not just the Connection tab properties. Also verify that the BizTalk host service account in production has the same DB2 COLLECTION permissions as the account used in testing.
What does "Package not found" mean and how do I fix it in BizTalk HIS?
Package not found (DB2 SQLCODE -805 or SQL0805N) means the OLE DB Provider for DB2 is trying to execute a SQL statement using a DRDA package that doesn't exist in the Package Collection you specified. This happens when the Package Collection name is wrong, when the packages were never bound (first-time setup), or when packages were dropped during a DB2 maintenance operation. Fix it by confirming the Package Collection name with your DB2 DBA, verifying the connecting user has BIND authority on that collection, and then triggering a new connection to let the provider auto-bind the packages. If auto-bind is disabled on the host, your DBA will need to manually bind the packages using the HIS Data Access Tool.
My AS/400 DB2 connection keeps failing with authentication errors even though the password is correct, what's wrong?
AS/400 (DB2/400) only accepts user IDs and passwords in UPPER CASE. If you're entering credentials in mixed case, the first connection attempt will fail. The OLE DB Provider for DB2 does handle this by automatically retrying with forced UPPER CASE, but if you're seeing persistent failures, check whether the UDL file has saved credentials in lowercase (open it in Notepad to inspect). Also check whether a firewall or network proxy is intercepting the DRDA traffic on port 446 and somehow mangling the authentication packet, this is rare but does happen in environments with deep-packet inspection on mainframe traffic.
How do I find the correct LOCATION value for DB2 on a mainframe (MVS/OS/390)?
The LOCATION value for DB2 on MVS or OS/390 is defined in the DDF (Distributed Data Facility) configuration. Ask your mainframe administrator to look in the TSO Clist DSNTINST under the DDF definitions section, specifically the DSNTIPR panel in the DB2 installation manual. The full list of accessible locations is also queryable via SELECT * FROM SYSIBM.LOCATIONS if you already have a working DB2 connection. The LOCATION value is case-sensitive and must be entered exactly as it appears in the DDF configuration, typically all uppercase.
Should I use SNA or TCP/IP transport for BizTalk Host Integration Server in a new deployment?
For any new BizTalk HIS deployment, use TCP/IP unless you have a specific requirement to use SNA LU6.2. TCP/IP is the modern DRDA transport, it's simpler to configure (just Network Address and port 446), easier to troubleshoot with standard network tools, and doesn't require SNA Server infrastructure. SNA LU6.2 transport requires APPC Local LU Alias, APPC Mode Name, and APPC Remote LU Alias configuration in SNA Server, significantly more moving parts. The only scenarios where SNA still makes sense are legacy environments where the mainframe network team hasn't opened TCP/IP DRDA access, or where specific SNA security features are required by organizational policy.
What APPC Mode Name should I use for BizTalk orchestrations that do real-time transaction processing?
For real-time transactional BizTalk orchestrations, use #INTER (interactive) as your APPC Mode Name. This mode is optimized for low-latency, interactive workloads. If your organization has security policies around routing, use #INTERSC instead, which is interactive with minimal routing security. Avoid using #BATCH or #BATCHSC for anything latency-sensitive, batch modes have different pacing parameters tuned for high-throughput bulk operations, not the request-response pattern typical in BizTalk orchestrations. Always confirm your mode name choice with your SNA Server administrator, because the mode name must match the host configuration exactly, a mismatch causes APPC session allocation failures at the host.