BizTalk Server deployment: The database or the database version is incompatible with the installed version of this product

Errors rarely appear alone; from time to time, it’s as if a project is determined to challenge you. But I find it rather enjoyable. It offers me inspiration and creative material for writing! Today’s U found an unfamiliar (or rare) problem that happened while I was migrating an old BizTalk Server 2013 solution into a recent version of the BizTalk Server.

Following the migration of the Visual Studio solution to a newer version, which also involved changing the target .NET framework, I encountered the following error when attempting to deploy the BizTalk Server Visual Studio solution:

The database or the database version is incompatible with the installed version of this product.


Normally, when we are migrating side-by-side BizTalk Server solutions, that means that we are creating a new BizTalk Server developer environment that, most of the time, does not have access to the previous environment. But you must know that if you copy a BizTalk Server Visual Studio folder solution from the old environment to the new one, it will also copy the *.btproj.user files. This is an XML file that contains not only the BizTalk deployment Settings but also several personal user settings like References path, test file names, and so on.

Regarding BizTalk deployment properties, all this setting are stored in the “*.btproj.user” file:

  • Application Name (ApplicationName): This is the name of the BizTalk application that we want to deploy the assemblies in this project. If the application already exists, the assemblies will be added to it when you deploy the project. If the application does not exist, the application will be created. If this field is blank, the assemblies will be deployed to the default BizTalk application in the current group (“BizTalk Application 1”). Names that include spaces must be enclosed in double quotation marks (“).
  • Configuration Database (ConfigurationDatabase): This is the name of the BizTalk Management database for the group. The default value is “BizTalkMgmtDb”.
  • Server (Server): This is the name of the SQL Server instance that hosts the BizTalk Management database on the local computer. By default, this is usually the name of the local computer.
  • Redeploy (Redeploy): Boolean property that indicates if you want to allow redeployments from within Visual Studio. Setting this to “True” (the default) enables you to redeploy the BizTalk assemblies without changing the version number.
  • Install to Global Assembly Cache (Register): Setting this to “True” (the default) installs the assemblies to the Global Assembly Cache (GAC) on the local computer when you install the application. Set this to False only if you plan to use other tools for this installation, such as gacutil.
  • Restart Host Instances (RestartHostInstance): Setting this to “True” automatically restarts all host instances running on the local computer when the assembly is redeployed. If set to False (the default), you must manually restart the host instances when redeploying an assembly.

Well, if you do not change, it will contain the previous SQL Server name and instance.

So, if this SQL Server is accessible by this machine and if you try to deploy the solution, you will get an error saying that the database version is incompatible because now you are using a higher version of the product.


The solution is quite simple to accomplish:

  • Access the Deployment tab of the Properties of each BizTalk Server project inside the solution.
  • And make sure that you set correctly at least the Server name (or name and instance)

If you want to play safe, it will give you a little bit of more work, but you can:

  • Close the solution.
  • 2Open Explorer and delete *.btproj.user files.
  • Reopen the solution, reconfigure the Deployment properties – this time mainly the Application name, because the rest will be properly configured by default – rebuild and deploy the solution.

Both these options will fix this problem.

Hope you find this helpful! So, if you liked the content or found it helpful and want to help me write more content, you can buy (or help buy) my son a Star Wars Lego! 

Author: Sandro Pereira

Sandro Pereira lives in Portugal and works as a consultant at DevScope. In the past years, he has been working on implementing Integration scenarios both on-premises and cloud for various clients, each with different scenarios from a technical point of view, size, and criticality, using Microsoft Azure, Microsoft BizTalk Server and different technologies like AS2, EDI, RosettaNet, SAP, TIBCO etc. He is a regular blogger, international speaker, and technical reviewer of several BizTalk books all focused on Integration. He is also the author of the book “BizTalk Mapping Patterns & Best Practices”. He has been awarded MVP since 2011 for his contributions to the integration community.

Leave a Reply

Your email address will not be published. Required fields are marked *


Back to Top