Modifier

Some Known Issues in Business Central On-premises

  • Article

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

Note

The article doesn't include a complete list of known issues. Instead, it addresses some common issues that you might experience or might consider when upgrading to a version. If you're aware of issues that aren't in this article, or you'd like more help, see Resources for Help and Support.

Error importing control add-in files from the client

Applies to: Upgrade to version 23.3

Problem

When you try to import an 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 follwoing 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:

Table Field
1251 "Text-to-Account Mapping" 11700 "Text-to-Account Mapping (Code[10])
1252 "Bank Pmt. Appl. Rule" 11700 "Bank Pmt. Appl. Rule Code" (Code[10])

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 a Azure VM running Windows Server, the following error occurs:

Web Server Components

Fatal error during installation

Possible cause

This error will typically occur 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 may not be able to sign in. In the event viewer, you'll 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 may 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.

Table File
Table 49 "Invoice Post. Buffer" InvoicePostBuffer.Table.al
Table 265 "Document Entry" DocumentEntry.Table.al
Table 269 "G/L Account Net Change" GLAccountNetChange.Table.al
Table 338 "Entry Summary" EntrySummary.Table.al
Table 491 "Parallel Session Entry" ParallelSessionEntry.Table.al
Table 1670 "Option Lookup Buffer" OptionLookupBuffer.Table.al
Table 1754 "Field Content Buffer" FieldContentBuffer.Table.al
Table 6305 "Power BI Chart Buffer" PowerBIChartBuffer.Table.al
Table 6302 "Power BI Report Buffer" PowerBIReportBuffer.Table.al
Table 7330 "Bin Content Buffer" BinContentBuffer.Table.al

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'll get an error stating that the table cannot 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 non-temporary records to these tables, you'll 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 non-temporary records in these base application tables to use other tables.

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'll 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'll 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 workaround 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.

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 may 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:

Local 14 version Tables
CH
  • QRBill Buffer
  • QRBill Billing Detail
  • QRBill Billing Info
  • QRBill Layout QRBill
  • QRBill Setup
  • VAT Reg. No. Srv. Template
  • VAT Registration Log Details
NA
  • VAT Reg. No. Srv. Template
  • VAT Registration Log Details

Note

You don't experience this problem with table objects in other Microsoft extensions because the primary keys are named KEY1.

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:

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.

Note

The table migration feature was introduced in version 15.3. For more information, see Migrating Tables and Fields Between Extensions.

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'll 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 will fail because Business Central can't obtain an access token for connecting to the service.

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

Failed to acquire authorization token for <service>.

In the event log, you'll 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 will fail.

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>"

See Also

Upgrading to Business Central