Some Known issues in Business Central on-premises

This article describes some known issues in Business Central versions. These issues can affect installation, upgrade, and various operations of Business Central on-premises.

Renamed tables and fields in subscription billing extension cause synch errors on upgrade

Applies to: Upgrade from 25.X

Problem

Several tables and fields are renamed in the subscription billing extension for version 26. These changes prevent you from syncing the extension to the tenant database when upgrading to version 26.0 or later. When you try to sync the extension, you get errors like the following:

Table 8001 Contract Renewal Line :: The table 'Contract Renewal Line' cannot be located. Removing tables is not allowed unless they are temporary or are being moved by migration to another app.

Table 8003 Price Update Template :: The field 'Contract Filter' cannot be located. Removing fields is not allowed.

Workaround

If no custom application code depends on the renamed tables and fields, force sync the extension using the -Mode ForceSync parameter:

Sync-NAVApp -ServerInstance $NewBcServerInstance -Name "Subscription Billing" -version $NewVersion -Mode ForceSync

Force sync might cause data loss if custom code depends on the renamed tables and fields in the extension. To prevent data loss, refactor the custom code to match the extension's latest database schema before upgrading.

Renamed tables and fields

This section lists the new names for tables and fields. (ff) indicates a flow field.

Table 8051 "Service Contract Setup" → "Subscription Contract Setup"

Table 8004 "Contract Price Update Line" → "Sub. Contr. Price Update Line"

Table 8001 "Contract Renewal Line" → "Sub. Contract Renewal Line"

Table 8002 "Planned Service Commitment" → "Planned Subscription Line"

Table 8019 "Contract Analysis Entry" → "Sub. Contr. Analysis Entry"

Table 8062 "Customer Contract Line" → "Cust. Sub. Contract Line"

Table 8065 "Vendor Contract Line" → "Vend. Sub. Contract Line"

Table 8066 "Customer Contract Deferral" → "Cust. Sub. Contract Deferral"

Table 8072 "Vendor Contract Deferral" → "Vend. Sub. Contract Deferral"

Table 8010 "Imported Customer Contract" → "Imported Cust. Sub. Contract"

Table 8008 "Imported Service Object" → "Imported Subscription Header"

Table 8009 "Imported Service Commitment" → "Imported Subscription Line"

Table 8007 "Overdue Service Commitments" → "Overdue Subscription Line"

Table 8068 "Sales Service Commitment" → "Sales Subscription Line"

Table 8069 "Sales Service Comm. Archive" → "Sales Sub. Line Archive"

Table 8057 "Service Object" → "Subscription Header"

Table 8059 "Service Commitment" → "Subscription Line"

Table 8073: Service Commitment Archive → Subscription Line Archive

Table "Service Comm. Package Line" → "Subscription Package Line"

Table 8016 "Usage Data Subscription" → "Usage Data Supp. Subscription"

Only fields renamed

Table 8070 "Subscription Billing Cue"

Table 8061 "Billing Line"

Table 8064 "Billing Line Archive"

Table 8003 "Price Update Template"

Table 8017 "Generic Import Settings"

Table 8006 "Usage Data Billing"

Table 8018 "Usage Data Generic Import"

Only tables renamed

Number series creation doesn't work in Business Central 25.2 on-premises

Applies to: 25.2

Problem

If you try to create a number series, you get the following error:

The filter on Series Code was altered by an event subscriber. This is a programming error. Please contact your partner to resolve this issue.

Workaround

Upgrade to 25.3 or later.

Different installation path in 25.2

Applies to: 25.2

25.2 includes internal database schema changes with the following consequences:

• New platform version 25.2 instead of 25.0.
• Different installation path than 25.0 and 25.1. Instead of using folder '250', components are installed in folder '252', for example: C:\Program Files\Microsoft Dynamics 365 Business Central\252.

Future updates like 25.3 and 25.4 will also use platform number '25.2' and installation folder '252'.

Installation fails because PowerShell 7 is already installed

Applies to: Installation of version 24.0 or 24.1

Problem

When you try to install the Business Central Server using the setup.exe program of version 24.1, the installation fails with the following error:

Microsoft Dynamics 365 Business Central Build NNNNN
Error Report

Setup Components
The component was rolled back.

PowerShell 7
PowerShell 7 for the commandlets
Fatal error during installation.

In the installation log or Windows Event Viewer, you get an error message similar to A newer version of PowerShell is already installed.

Possible cause

Windows PowerShell 7.4.2 or later is already installed on the Business Central Server machine. The Business Central setup.exe will automatically install PowerShell 7.4.2, but it should only do so if the machine doesn't have PowerShell installed or it has a version earlier than 7.4.2. In version 24.1, instead of skipping the PowerShell installation when it should, the setup.exe tries to install PowerShell but fails.

PWSH.exe

Workaround

Uninstall PowerShell 7 from the Business Central Server machine, then run setup.exe again.

Learn how to uninstall an app or program in Windows.

Error importing control add-in files from the client

Applies to: Upgrade to version 23.3

Problem

When you try to import a control add-in file client from the Control Add-ins page in the client by using the Control Add-in Resource > Import, you get the following error:

Can't open file`

[URL] can't open files in this folder because it cotains system files`

[URL] is the URL of your Business Central web client, for example, http://localhost:8080.

Workaround

You have two options to work around this issue:

• Use the Set-NAVAddin cmdlet of the Business Central Administration Shell as described in Upgrade control add-ins.
• If you want to use the Business Central web client, then copy the files to another folder on your PC, like Documents or Downloads, and try again.

Removed table fields in the Czech (CZ) base application cause sync errors

Applies to: Upgrade to version 23

Problem

As part of the delocalization process of the Czech (CZ) version of Business Central, Microsoft moved Czech-specific functionality into separate applications. As a result, the following fields have been removed and the primary keys modified in the Czech (CZ) base application, version 23:

These changes can lead to the following errors when you try to synchronize the base application with the tenant during upgrade:

Sync-NAVApp : Table 1251 Text-to-Account Mapping :: The field 'Text-to-Account Mapping Code' cannot be located. Removing fields is not allowed.
Table 1251 Text-to-Account Mapping :: Changing fields for the key 'Key1' is not allowed. Previous list: 'Text-to-Account Mapping Code', 'Line No.', new List: 'Line No.'.
Table 1252 Bank Pmt. Appl. Rule :: The field 'Bank Pmt. Appl. Rule Code' cannot be located. Removing fields is not allowed.
Table 1252 Bank Pmt. Appl. Rule :: Changing fields for the key 'Key1' is not allowed. Previous list: 'Bank Pmt. Appl. Rule Code', 'Match Confidence', 'Priority', new List: 'Match Confidence', 'Priority'.

Workaround

If you're upgrading from version 22, use the Sync-NavApp cmdlet to synchronize the base application in the ForceSync mode during upgrade, for example:

SyncNavApp -ServiceInstance <BC 23 server instance> -Name "Base Application" -Version <23 version number> -Mode ForceSync

If you're upgrading from version 21 or earlier, the workaround is slightly different. First, ensure that no duplicate records will exist in either table 1251 "Text to Account Mapping" or table 1252 "Bank Payment Application Rule" after upgrade. To do this, complete one of the following tasks before you upgrade to version 23:

• Manually delete any duplicate records in either of the tables, or
• Upgrade to the latest version 22 that's compatible with the version 23 you're upgrading to. With version 22, the necessary data modifications to handle duplicate records are included as part of the upgrade procedures.

Once you completed either of these tasks, upgrade to version 23 as usual. Don't forget to synchronize the base application using the ForceSync mode with the Sync-NavApp cmdlet.

Web server components fatal error during installation on Azure virtual machine (VM)

Applies to: Version 20 and 21

Problem

When you try to install the Business Central Web Server components using setup.exe on an Azure VM running Windows Server, the following error occurs:

Web Server Components

Fatal error during installation

Possible cause

This error typically occurs on a VM where the Business Central Web Server hasn't been installed before. It happens because setup is trying to install Windows Server Hosting and Microsoft .NET Core Runtime on the VM but they're already installed, causing a conflict.

Workaround

Uninstall Windows Server Hosting and Microsoft .NET Core Runtime from the VM, then run setup.exe again.

Users can't sign in to the web client after upgrade to 19.0

Applies to: Upgrade to 19.0

Problem

If the Business Central Web Server is configured for Windows authentication, users might not be able to sign in. In the event viewer, you see the following exception:

System.PlatformNotSupportedException: Operation is not supported on this platform.
   at System.Func`2.BeginInvoke(T arg, AsyncCallback callback, Object object)
   at Microsoft.Dynamics.Nav.Client.ConnectionEstablisher.TestSpnSettings(ConnectFailedEventArgs connectFailedArgs)

Workaround

Set the UnknownSpnHint setting in the navsettings.json file of Business Central Web Server by following the guidelines at in Configuring Business Central Web Server instance.

Tables changed to temporary might prevent synchronizing new base application version

Applies to: Upgrade from version 17.X or earlier to any later version

Problem

Starting in version 18, the following base application tables are now temporary tables, as specified by the TableType property. Depending on how you're using these tables, this change may affect the upgrade from version 17 or earlier to a later version.

Impact

With this change, these tables must be empty to complete the upgrade. If a table isn't empty, you can't synchronize the new version of the base application. In this case, you get an error stating that the table can't be deleted from the database because it contains data, for example:

Cannot delete the Document Entry table from the database because it contains data.

So if there are records in these tables, or the application includes custom code that stores nontemporary records to these tables, you have to make some changes before you can run the upgrade.

Workaround

Before you upgrade, either move the records to new tables or delete the records from the tables. Also, rewrite the custom application code that's stores the nontemporary records in these base application tables to use other tables.

NavUserPassword authentication doesn't work after upgrade to version 18

Applies to: Upgrade to 18.0-18.2

Problem

When you upgrade to version 18 from an earlier major version, authentication that's based on NavUserPassword credential type no longer works for existing users. Passwords aren't considered valid anymore.

Impact

When users try to sign in to Business Central, they get an error, similar to the following message:

The specified user name or password is not correct, or you do not have a valid user account in Dynamics 365 Business Central

In event viewer, you see the following error:

Your user name <name> or password is incorrect, or you do not have a valid account in Dynamics 365 Business Central.

Workaround

To work around this issue, activate the EnableLegacyIterationCount feature switch by completing these steps.

1. Run the Business Central Administration Shell as an administrator.

   For more information, see Run Business Central Administration Shell.

2. Run the following command to determine which feature switches are enabled:

   Get-NAVServerConfiguration -ServerInstance $ServerInstanceName -KeyName "FeatureSwitchOverrides"
   

   Replace$ServerInstanceName with the Business Central Server instance name.

3. Depending on what was returned in step 2, run one of the following commands to enable the EnableLegacyIterationCount feature switch:

   • If the nothing was returned, run the following command:

     Set-NAVServerConfiguration -ServerInstance $ServerInstanceName -KeyName "FeatureSwitchOverrides" -KeyValue "EnableLegacyIterationCount"
     

   • If one or more entries were returned, run the following command:

     Set-NAVServerConfiguration -ServerInstance $ServerInstanceName -KeyName "FeatureSwitchOverrides" -KeyValue ((Get-NAVServerConfiguration -ServerInstance $ServerInstanceName -KeyName "FeatureSwitchOverrides") + (",EnableLegacyIterationCount"))
     

4. Restart the server.

   Restart-NAVServerInstance -ServerInstance $ServerInstanceName
   

Notes

• Activating the EnableLegacyIterationCount feature switch is only required if you have existing users that are set up with passwords for the NavUserPassword authentication. So if you want to set up NavUserPassword from scratch after upgrade, you don't need to enable the EnableLegacyIterationCount feature switch for it to work.

• When the EnableLegacyIterationCount feature switch is enabled, you can create new users with passwords and assign or change passwords of existing users.

• You can activate and deactivate the EnableLegacyIterationCount feature switch for the deployment at any time, but be aware of the following behavior:

  • Passwords that were assigned to users when the EnableLegacyIterationCount feature switch was activated, won't work when the EnableLegacyIterationCount feature switch is deactivated.

  • Passwords that were assigned to users when the EnableLegacyIterationCount feature switch was deactivated, won't work when the EnableLegacyIterationCount feature switch is activated.

    In these cases, as an administrator, you'll have to assign new passwords to the affected users.

• This feature switch is activated per server instance, so it pertains to all tenants in a multitenant deployment.

NavUserPassword authentication performance after upgrade to version 18

Applies to: Upgrade to 18.X

Problem

When you upgrade to version 18 from an earlier major version, authentication that's based on the NavUserPassword credential type takes longer than it did in previous versions. This reason is that the password algorithm has been updated in version 18. The extra time it takes per authentication isn't noticeable to a normal user. But in a solution that has a heavy authentication load, for example from multiple and repeated web service calls, the extra time might be significant.

Workaround

One solution is to activate the EnableLegacyIterationCount feature switch, as described in the previous issue. This feature switch sets the server instance to use the same authentication algorithm used in version 17. Another solution is to change the authentication method to either OAuth or Web service access key. With these authentication methods, the password isn't stored in Business Central in a hashed format.

Data upgrades fail because of missing $system fields in the Permission and Permission Set tables

Applies to: Upgrade to 18.0-18.1

Problem

When you upgrade to version 18 from an earlier major version, and the Business Central Server instance is configured to use permission sets from data, the data upgrade fails because some system fields aren't added to Permission and Permission Set tables.

Impact

When you run the Start-NAVDataUpgrade or Start-NAVAppDataUpgrade against the base application, the cmdlet fails. You'll get an error message that the following columns in the Permission Set table are missing or invalid:

• $systemCreatedAt
• $systemCreatedBy
• $systemModifiedAt
• $systemModifiedBy

Workaround

Upgrade to version 18.2 or later.

Package Microsoft .NET Core Windows Server Hosting failed with error

Applies to: All versions up to and including version 18.0.

Problem

When you install Business Central on premises, installation may fail with the error Package Microsoft .NET Core Windows Server Hosting failed with error, or with error code 1638, when the installer attempts to install prerequisite components.

This problem occurs when a version of Windows Server Hosting newer than version 2.1.14 is installed on the server, because Business Central installer attempts to install version 2.1.14.

The issue only occurs when the currently installed version is a newer minor version, not a newer major version of Windows Server Hosting.

Impact

Installation will fail and will be rolled back.

Workaround

The issue can be resolved in different ways:

• Manually install Windows Server Hosting version 3 or later before you install Business Central components.
• Uninstall Windows Server Hosting from your server before you install Business Central
• Use the installer from Business Central version 18.1 or later. In these versions, Business Central installer skips installing Windows Server Hosting components if it determines that newer Windows Server Hosting components are already installed.

Primary key mismatch between converted tables in local 14 versions and Microsoft Base Application

Applies to: Upgrade from 14.18-14.X to 15.12-15.X, 16.7-16.X, or 17.1-17.X

Problem

In some local versions, new table objects were added as part of a minor update. In version 14, which is still C/AL based, the primary keys of these tables are unnamed. When you convert the tables from CAL to AL using the txt2AL tool, primary keys are given the name Key1. In version 15, 16, and 17, which is fully AL-based, these tables have been moved to Microsoft base application extension, and the primary keys have the name PK. This difference can cause problems when you upgrade to use the Microsoft Base Application because it introduces breaking changes.

The affected local versions and tables include:

Impact

If you don't resolve this conflict, you'll experience problems when upgrading a customized version 14 (C/AL) application to the Microsoft Base Application.

For example, consider the following articles:

• Upgrading Customized C/AL Application to Microsoft Base Application Version 16
• Upgrading Customized C/AL Application to Microsoft Base Application Version 17

During this upgrade process, you'll create two versions of an extension referred to as the table migration extension. This extension is used for transferring ownership of existing tables in the database to other extensions. The first version contains table objects. The second version contains a migration.json file instead of the table objects. When you try synchronize the second version of the table migration extension (Task 13.5 or Task 12.6), you'll get the following errors for each affected table:

Table <table name> :: The previous primary key 'Key1' cannot be located. Changing the primary key is not allowed.

Table <table name> :: Introducing a new key 'PK' as the primary key is not allowed. Please make the key 'Key1' the primary key again.

Workaround

To avoid these errors, after converting the version 14 tables to AL, rename instances of the primary key Key1 to PK in the affected table objects before building your extensions.

• If you're following the upgrade articles listed above, do this change as part of Task 2. If you've already published the first table migration extension with the wrong key names, restore the databases and go through the upgrade again, starting from Task 2.
• Also make these changes if you're only doing a technical upgrade. This way, you won't run into problems later if eventually uptake the Microsoft Base Application.

For each affected table object, do the following steps:

1. Open the .al file.

2. Locate the primary key definition. For example:

   keys
   {
       key(Key1; "Primary key")
       {
           Clustered = true;
       }
   }
   

3. Change the name from Key1 to PK. For example:

   keys
   {
       key(PK; "Primary key")
       {
           Clustered = true;
       }
   }
   

Enum type fields not transferred as part of schema migration between extensions

Applies to: Upgrade to 15.3-15.11 and 16.0-16.4

Problem

The table migration feature fails to transfer data from a table object to a table extension object that introduces an enumeration.

Impact

You'll experience this issue in the following scenarios:

• Upgrading a customized version 14 solution to version 15 or 16
• Migrating data from one extension to another.

The issue occurs when synchronizing extensions. You get an error similar to one of the following messages:

Sync-NAVApp : The metadata object Enum <ID> was not found.

Message App Sync Exception -- Microsoft.Dynamics.Nav.Types.NavMetadataNotFoundException: The metadata object Enum <ID> was not found.

Workaround

• If you're upgrading from version 14, use 15.12 (or later) or 16.5 (or later) as the target version.

• If you're migrating data between extensions, upgrade your solution to 15.12 (or later) or 16.5 (or later).

$systemModifiedAt fields in tables not populated during upgrade

Applies to: Upgrade from 14.0-14.X to 17.X

Problem

Business Central version 17 introduced data audit fields on tables. When you upgrade from version 15 or 16, the $systemModifiedAt field is populated with values from field 5120 ModifiedOn in table 5151 Integration Record. However, this mapping doesn't work in a version 14-to-17 upgrade.

Impact

When upgrading from version 14 to version 17, the $systemModifiedAt field will be blank.

Workaround

Upgrade to version 15 or 16 before upgrading to version 17.

Wrong .NET assemblies for external connected services

Applies to: Upgrade to 16.5

Problem

Version 16.5 includes the wrong .NET 4.5 assemblies for connecting to external services that use OAuth, like Common Data Service.

Impact

In the Business Central client, you can set up external service connections from the Service Connections page. When you try to set up a connection, it fails because Business Central can't obtain an access token for connecting to the service.

In the client, you get an error similar to the following message:

Failed to acquire authorization token for <service>.

In the event log, you see an error similar to the following message:

Could not load file or assembly 'Microsoft.Identity.Client, Version=4.14.0, Culture=neutral, PublicToken=0a613f4dd989e8e' or one of its dependencies. The located assembly's manifest location does not match the assembly reference.

Workaround

There are two workarounds for this issue:

1. Upgrade to 16.6 or later.

2. Install the required assemblies:

   1. Go to https://www.nuget.org/packages/Microsoft.Identity.Client/4.14.0.

   2. Under Info, select Download package.

   3. Extract the contents of the nupkg file to a folder.

      There are different ways to extract the content of nupkg file. An easy way is to change the file extension from .nupkg to .zip. Then, extract the files like you would do with any .zip file.

   4. Copy the files in the \lib\net45 folder to the Service folder of the Business Central Server installation. Replace the existing files when prompted.

      The default folder is C:\Program Files\Microsoft Dynamics 365 Business Central\160\Service.

   5. Restart the Business Central Server instance.

Help Server for India preview missing files

Applies to: Upgrade to 17.X

Problem

The installation media (DVD) is missing required HTML files for the Help Server.

Impact

The Help Server installation fails.

Workaround

Install Help Server without the HTML files for local functionality, then pick up the content from GitHub instead.

Business Central Server Administration tool doesn't work for multitenant server instances

Applies to: Upgrade to 17.0-17.1

If a Business Central Server instance is configured as a multitenant instance, you can't manage the tenants by using the Business Central Server Administration tool.

Impact

When you try to use the Tenant node in the Business Central Server Administration tool, you get a message: The MMC has detected an error in the snap-in and will unload it. This message is followed by:

FX:{ba484c42-ed9a-0170-925f-23e64e686fd0}

Value cannot be null. Parameter name: objectToValidate at Microsoft.ManagementConsole.BaseCollection.OnValidate(Object objectToValidate, Boolean testForDuplicate) at System.Collections.CollectionBase.System.Collections.IList.Add(Object value) at CallSite.Target(Closure , CallSite , NodeSubItemDisplayNameCollection , Object ) at System.Dynamic.UpdateDelegates.UpdateAndExecuteVoid2[T0,T1](CallSite site, T0 arg0, T1 arg1) at Microsoft.Dynamics.Nav.ManagementUI.NavTenantsListView.RefreshWithNodeStateChangedCheck(IList1 tenants, ResultNodeCollection currentResultNodes) at Microsoft.Dynamics.Nav.ManagementUI.NavTenantsListView.RefreshCore() at Microsoft.Dynamics.Nav.ManagementUI.NavTenantsListView.OnInitialize(AsyncStatus status) at Microsoft.ManagementConsole.View.ProcessRequest(Request request) at Microsoft.ManagementConsole.ViewMessageClient.ProcessRequest(Request request) at Microsoft.ManagementConsole.Internal.IMessageClient.ProcessRequest(Request request) at Microsoft.ManagementConsole.Executive.RequestStatus.BeginRequest(IMessageClient messageClient, RequestInfo requestInfo) at Microsoft.ManagementConsole.Executive.SnapInRequestOperation.ProcessRequest() at Microsoft.ManagementConsole.Executive.Operation.OnThreadTransfer(SimpleOperationCallback callback)

Workaround

Use the Business Central Administration Shell. This error is fixed in later updates.

Sync-NAVApp error: Parameter @objname is ambiguous or the claimed @objtype (INDEX) is wrong

Applies to: Upgrade from 14.X

Problem

You get the following error when running Sync-NAVApp cmdlet on the base application:

Sync-NAVApp : The following SQL error was unexpected:

Either the parameter @objname is ambiguous or the claimed @objtype (INDEX) is wrong.

Either the parameter @objname is ambiguous or the claimed @objtype (INDEX) is wrong.

Caution: Changing any part of an object name could break scripts and stored procedures.

Workaround

This occurs when a key fails to get renamed. To fix the problem, identify the key that fails to get renamed, for example, by using the event log or SQL profiler. Then, disable the key by using Dynamics NAV Development Environment.

Business Central Server instance fails to start after changing a port number directly in the CustomSettings.config file

Applies to: Upgrade to 21.x

Problem

You get errors in the Event Log similar to the following errors when trying to start the Business Central Server instance after changing a port number directly in it's CustomSettings.config file:

• Message (HttpSysException): Failed to start service with CLR type Microsoft.Dynamics.Nav.Service.AspNetCore.AspNetCoreApiHost, API type ClientApi and address http://gc1662:8085/BC210/client.
• Failed to start service with CLR type Microsoft.Dynamics.Nav.Service.AspNetCore.AspNetCoreApiHost, API type ClientApi and address
• The service MicrosoftDynamicsNavServer$BC210 failed to start. This could be caused by a configuration error. Detailed error information: Microsoft.AspNetCore.Server.HttpSys.HttpSysException (0x80004005): Access is denied
• Type: Microsoft.AspNetCore.Server.HttpSys.HttpSysException; Message: Access is denied

Impact

After upgrading to version 21.x, you notice that the Business Central Server Administration tool is no longer available, because it has been removed in version 21.x. If you then try to update certain port numbers (for example, ClientServicesPort ) directly in the server instance's CustomSettings.config file, you may get the errors described above when you try to start the server instance.

Workaround

Avoid updating the CustomSetting.config file directly. Instead, use the Business Central Administration Shell with the Set-NAVServerConfiguration cmdlet. This will automatically grant the required Namespace Reservation permissions for the relevant port.

Alternatively, you could grant the required Namespace Reservation permissions manually for the relevant port by running the appropriate NETSH command in an administrator command prompt on the Business Central Server machine, for example:

netsh http add urlacl url=http://+:<PORT NUMBER>/<BC SERVICE NAME>/ user="<BC SERVICE ACCOUNT>"

Related information

Upgrading to Business Central