# Troubleshoot on-premises deployments

This topic provides troubleshooting information for on-premises deployments of Microsoft Dynamics 365 for Finance and Operations.

## Access Service Fabric Explorer

You can access Service Fabric Explorer in a web browser by using the default address, https://sf.d365ffo.onprem.contoso.com:19080.

To verify the address, note the value that was used in the "Create DNS zones and add A records" section of the appropriate setup and deployment topic for your environment:

You can access the site only if the client certificate is in cert:\CurrentUser\My on the machine that you're accessing the site on. (In Certificate Manger, go to Certificates - Current User > Personal > Certificates.) When you access the site, select the client certificate when you're prompted.

## Monitor the deployment

### Identify the primary orchestrator

To determine the machine that is the primary instance for stateful services such as a local agent, in Service Fabric Explorer, expand Cluster > Applications > <intended application example> LocalAgentType > fabric:/LocalAgent/OrchestrationService > (GUID).

The primary node is shown. For stateless services or the remaining applications, you must check all the nodes.

Note the following points:

• OrchestrationService orchestrates the deployment and servicing actions for Finance and Operations.
• ArtifactsManager downloads files from Microsoft Azure cloud storage to the local agent file share. It also unzips the files into the required format.

### Review the orchestrator event logs

From the primary OrchestrationService orchestrator machine, in Event Viewer, review Applications and Services Logs > Microsoft > Dynamics > AX-LocalAgent.

Note that you must select the Details tab to view the full error message.

The following modules must be installed:

• Common
• ReportingServices
• AOS
• FinancialReporting

The following commands must be run:

• Setup
• Dvt (deployment verification test)
• Cleanup (used to service and delete an environment)

The following folders contain additional information:

• AX-SetupModuleEvents
• AX-SetupInfrastructureEvents
• AX-BridgeService

Event viewer tip for reviewing Dynamics entries: In Event viewer, right-click on Custom Views and select Create Custom View.

Select the Event logs drop down list, and select Dynamics, as shown.

Note, also look at Administrative Events in Custom Views.

### Service Fabric Explorer

Note the state of the cluster, application, and nodes. For information about how to access Service Fabric Explorer, see Access Service Fabric Explorer.

#### Error: "Partition is below target replica or instance count"

This error isn't a root error. It indicates that the status of each node isn't ready. For AXSFType (AOS), the status might still be InBuild.

Use Event Viewer on the machines related to the error message to view the latest activity.

#### AXSFType

For AXSFType (AOS), if a status of InBuild is shown, review the DB Sync status and other events from Application Object Server (AOS) machines.

To diagnose errors, use Event Viewer to review the following event logs:

• Applications and Services Logs > Microsoft > Dynamics > AX-DatabaseSynchronize
• Custom Views > Administrative Events

#### Service Fabric logs

You can find additional details about Azure Service Fabric applications in the log files at C:\ProgramData\SF\<OrchestratorMachineName>\Fabric\work\Applications\LocalAgentType_App<N>\log.

### Lifecycle Services

Note the current deployment status for the environment in Microsoft Dynamics Lifecycle Services (LCS).

## Time-out error occurs when a Service Fabric cluster is created

Run Test-D365FOConfiguration.ps1 as noted in the "Set up a standalone Service Fabric cluster" section of the appropriate setup and deployment topic for your environment, and note any errors:

Be sure to complete these steps:

• Verify that the Service Fabric Server client certificate exists in the LocalMachine store on all Service Fabric nodes.
• Verify that the Service Fabric Server certificate has the access control list (ACL) for Network Service on all Service Fabric nodes.
• Review the antivirus exclusions that are noted in Environment setup.

## Time-out error occurs while you're waiting for Installer Service to be completed for machine x.x.x.x

Only one node type is supported for each Internet Protocol (IP) address (that is, for each machine). Check whether the nodes are being reused on the same machine. For example, AOS and ORCH must not be on the same machine, and ConfigTemplate.xml must be correctly defined.

## Remove a specific application

We recommend that you use LCS to remove or clean up deployments. However, you can also use Service Fabric Explorer to remove an application as you require.

In Service Fabric Explorer, go to Application node > Applications > MonitoringAgentAppType-Agent. Select the ellipsis button [...] next to fabric:/Agent-Monitoring, and delete the application. Enter the full name of the application to confirm.

You can also remove MonitoringAgentAppType-Agent by selecting the ellipsis button and then selecting Unprovision Type. Enter the full name to confirm the removal of the application.

## Remove all applications from Service Fabric

The following script removes and unprovisions all Service Fabric applications except the LocalAgent and Monitoring agent for the LocalAgent. You must run this script on an orchestrator virtual machine (VM).

$applicationNamesToIgnore = @('fabric:/LocalAgent', 'fabric:/Agent-Monitoring')$applicationTypeNamesToIgnore = @('MonitoringAgentAppType-Agent', 'LocalAgentType')

Get-ServiceFabricApplication | 
Where-Object { $_.ApplicationName -notin$applicationNamesToIgnore } |
Remove-ServiceFabricApplication -Force

Get-ServiceFabricApplicationType | 
Where-Object { $_.ApplicationTypeName -notin$applicationTypeNamesToIgnore } |
Unregister-ServiceFabricApplicationType -Force

## Remove Service Fabric

To completely remove the Service Fabric cluster, follow these steps.

1. Run the following command.

.\RemoveServiceFabricCluster.ps1 -ClusterConfigFilePath .\ClusterConfig.json

2. If an error occurs, remove a specific node on the cluster by using the CleanFabric.ps1 command. You can find this command in C:\Program Files\Microsoft Service Fabric\bin\fabric\fabric.code.

3. Remove the C:\ProgramData\SF folder, if you're using the default location. Otherwise, remove the specified folder.

## Clean up an existing environment and redeploy

1. In LCS, open the project, and then, in the Environments section, delete the deployment.

The applications should start to disappear from Service Fabric Explorer in the environment. This process will take one to two minutes.

2. Access the orchestrator machine that contains LocalAgentCLI.exe, and follow these steps:

1. Run local agent cleanup.

.\LocalAgentCLI.exe Cleanup '<path of localagent-config.json>'

2. Remove Service Fabric.

.\RemoveServiceFabricCluster.ps1 -ClusterConfigFilePath '<path of ClusterConfig.json>'

3. If any nodes fail, run the CleanFabric.ps1 command. You can find this command in C:\Program Files\Microsoft Service Fabric\bin\fabric\fabric.code.

4. Remove the C:\ProgramData\SF\ folder on all Service Fabric nodes.

If access is denied, restart the machine, and try again.

3. Remove or update certificates as required.

Remove old certificates from all AOS, BI, ORCH, and DC nodes.

• The certificates exist in the following certificate stores: Cert:\CurrentUser\My\, Cert:\LocalMachine\My, and Cert:\LocalMachine\Root.
• If the Microsoft SQL Server setup will be modified, remove the SQL Server certificates.
• If the Active Directory Federation Services (AD FS) settings will be modified, remove the AD FS certificate.
4. Update the following configuration files as required:

• ConfigTemplate.xml
• ClusterConfig.json

For information about how to correctly fill in the fields in the templates, see the appropriate setup and deployment topic for your environment:

5. In LCS, open the project, and update the LCS on-premises connector as required.

1. Re-create the LCS on-premises connector for the environment, or edit the settings of an existing connector.

To obtain easy-to-copy values for LCS, use the .\Get-AgentConfiguration.ps1 script.

Deploy again by following the deployment documentation for Platform update 12 or for Platform update 8 and Platform update 11.

## Find the local agent values that are used

You can find local agent values in Service Fabric Explorer, under Cluster > Applications > LocalAgentType > fabric:/LocalAgent > and then select Details.

Alternatively, run the following Windows PowerShell command.

.\Get-AgentConfiguration.ps1 -ConfigurationFilePath .\ConfigTemplate.xml

## Install, upgrade, or uninstall a local agent

For information about local agent installation, see the appropriate setup and deployment topic for your environment:

You can also use the following upgrade and uninstall commands:

LocalAgentCLI.exe Install <path of localagent-config.json>
LocalAgentCLI.exe Cleanup <path of localagent-config.json>

Note

The cleanup command doesn't remove any files that were put in the file share. The file share can be reused.

## An error occurs when local agent services are started

When local agent services are started, you might receive the following error:

Could not load file or assembly 'Lcs.DeploymentAgent.Proxy.Contract, Version=1.0.0.0, Culture=neutral, PublicKeyToken=31bf3856ad364e35' or one of its dependencies.

This error means that the Strong name verification is turned on. You can turn off this verification by using Configure-PreReqs.ps1. To validate that the verification is no longer turned on, run Test-D365FOConfiguration.ps1.

## A "Validation in progress" message is shown for several minutes in LCS

Follow these steps to troubleshoot general issues with local agent validation.

1. Run Configure-PreReqs.ps1 on all orchestrator machines to configure the machines correctly.

2. Verify that the Test-D365FOConfiguration.ps1 script passes on all the orchestrator machines.

3. Verify that the installation of LocalAgentCLI.exe is successfully completed.

4. In Service Fabric Explorer, verify that all the applications are healthy.

5. If the applications aren't healthy, find the primary node for the service that is failing. In Event Viewer, look for events in the following locations:

• Custom Views > Administrative Events
• Applications and Services Log > Microsoft > Dynamics > AX-LocalAgent

## Local agent errors

### Issue

Error:

You might receive the following errors:

Unable to process commands

Unable to get the channel information

RunAsync failed due to an unhandled exception causing the host process to crash: System.ArgumentNullException: Value cannot be null. Parameter name: certificate

Reason: These errors can occur because the certificate that is specified for the OnPremLocalAgent certificate either isn't valid or isn't configured correctly for the tenant.

Steps: Follow these steps to resolve the error.

1. Run Test-D365FOConfiguration.ps1 on all orchestrator nodes to make sure that all checks pass.

2. Verify that the certificate that is specified in the local agent configuration is correct.

• Make sure that the thumbprint that you specify in LCS and in the ConfigTemplate.xml file has no special characters.

• The certificate should be the same certificate that is specified in the following section in infrastructure\ConfigTemplate.xml.

<Certificate type="Orchestrator" exportable="true" generateSelfSignedCert="true">
<Name>OnPremLocalAgent</Name>
<Thumbprint></Thumbprint>
<ProtectTo></ProtectTo>
</Certificate>

3. Make sure that the same certificate that is specified in the local agent configuration in LCS was used to complete the steps in the "Configure LCS connectivity for the tenant" section of the appropriate setup and deployment topic for your environment:

4. Uninstall the local agent.

5. Specify the correct certificate in the local agent configuration, and download the configuration file again.

6. Install the local agent again by using the new configuration file.

### Error

Error: The credentials supplied to the package were not recognized.

Reason: ACL not properly defined on certificates.

Steps: During servicing if receive “Unable to download asset…” error and the details shows "The credentials supplied to the package were not recognized", check to see if ACL was removed from client certificate on orchestrator machines.

To verify, run the following script on orchestrator machines and verify the ACL:

• .\Test-D365FOConfiguration.ps1

To resolve, run the following script to reset:

• .\Set-CertificateAcls.ps1

### Error

Error:

Reason: The file share that is specified in the local agent configuration isn't valid.

Steps: Follow these steps to resolve the error.

1. Verify that the specified share exists.

2. Verify that the local agent user has full permission on the share. The local agent user is the Domain Name System (DNS) name that is specified in the following section in ConfigTemplate.xml.

<ADServiceAccount type="gMSA" name="svc-LocalAgent$" refName="gmsaLocalAgent"> <DNSHostName>svc-LocalAgent.d365ffo.onprem.contoso.com</DNSHostName> </ADServiceAccount> 3. Make sure that the "Set up file storage" section of the appropriate setup and deployment topic for your environment is completed: 4. Uninstall the local agent. 5. Specify the correct file share in the local agent configuration, and download the configuration file again. 6. Install the local agent again by using the new configuration file. ### Error Error: Unable to get extract setup folder for command Reason: File share has been removed or changed. When doing a servicing operation, will run into the "Unable to get extract setup folder for command" error. Steps: To see what the file share is set to, go to SQL Server Management Studio and query on orchestrator database: select * from OrchestratorCommandArtifact where CommandId = ‘xxx’ ### Error Error: Login failed for user 'D365\svc-LocalAgent$'. Reason: Could not find a login matching the name provided. [CLIENT: 10.0.2.23]

Reason: The local agent user can't connect to the orchestrator database. This issue can occur because users have been deleted and then re-created in Active Directory Domain Services (AD DS). Therefore, the security identifier (SID) of the user has changed, and any access that was given to the user for the SQL Server or database no longer works.

Steps: Follow these steps to resolve the error.

1. Run the following script on the SQL Server instance.

.\Initialize-Database.ps1 -ConfigurationFilePath .\ConfigTemplate.xml -ComponentName Orchestrator

This script creates an empty orchestrator database, if an empty database doesn't already exist. It then adds the local agent user to the database and gives it db_owner permission.

After the correct permissions are provided, the application should automatically go to a healthy state.

2. If any settings, such as the fully qualified domain name (FQDN) of the SQL Server instance, the database name, or the local agent user, were provided incorrectly in LCS, change the settings, and then reinstall the local agent.

If the preceding steps don't resolve the issue, manually remove the local agent user from the SQL Server instance and the database, and then rerun the Initialize-Database script.

If you re-create a user in AD DS, remember that the SID will change. In this case, remove the previous SID for the user, and add a new SID.

### Error

Error: Unable to migrate database

Steps:

• If testing, you can start over with blank orchestrator database.

### Issue

When performing the Configure the databases procedure, if the SQL Server is a named instance, use parameter -DatabaseServer [FQDN/Instancename].

### Issue

The local agent user can't connect to the SQL Server instance or the database.

Steps: Follow these steps to resolve the error.

1. Delete the svc-LocalAgent user from the SQL Server primary node databases, and then remove the login from both servers.

2. Run the following scripts.

.\Initialize-Database.ps1 -ConfigurationFilePath .\ConfigTemplate.xml -ComponentName Orchestrator
.\Configure-Database.ps1 -ConfigurationFilePath .\ConfigTemplate.xml -ComponentName Orchestrator

These scripts don't work when an always-on setup is used. The database must be created in the primary node first and then replicated.

### Error

Error:

RunAsync failed due to an unhandled exception causing the host process to crash: System.Net.Http.HttpRequestException: An error occurred while sending the request. ---> System.Net.WebException: The remote name could not be resolved: 'lcsapi.lcs.dynamics.com'

Reason: The local agent machines can't connect to lcsapi.lcs.dynamics.com. Review the AX-BridgeService event log for "The remote name could not be resolved: 'lcsapi.lcs.dynamics.com'."

Steps: Follow these steps to resolve the error.

1. Run psping lcsapi.lcs.dynamics.com:80.

2. If you don't receive a response from the above command, contact the IT department at your organization. The firewall is blocking access to lcsapi, or proxy issues are occurring.

lcsapi.lcs.dynamics.com:443
uswelcs1lcm.queue.core.windows.net:443
www.office.com:443
dc.services.visualstudio.com:443
uswelcs1lcm.blob.core.windows.net:443
uswedpl1catalog.blob.core.windows.net:443

## Restart applications (such as AOS)

In Service Fabric, expand Nodes > AOSx > fabric:/AXSF > AXSF > Code Packages > Code. Select the ellipsis button (...), and then select Restart. Enter the code when you're prompted.

Service Fabric Explorer will display a message simillar to the following:

Because the minimum requirement is one SQL Server Reporting Services (SSRS) node and one Management Reporter (MR) node, you must pass in a parameter to skip PreUpgradeSafetyCheck.

Here are the steps that are used to upgrade Service Fabric in Windows PowerShell.

#Connect to Service Fabric Cluster. Replace 123 with server/star thumbprint and use appropriate IP address
Connect-ServiceFabricCluster -connectionEndpoint 10.0.0.12:19000 -X509Credential -FindType FindByThumbprint -FindValue 123 -ServerCertThumbprint 123

Get-ServiceFabricRegisteredClusterCodeVersion

#Note UpgradeReplicaSetCheckTimeout is to skip over PreUpgradeSafetyCheck for SSRS and MR, see <https://github.com/Azure/service-fabric-issues/issues/595>

To learn when a new Service Fabric release comes out, see the Azure Service Fabric team blog.

If you receive a warning in Service Fabric Explorer after you upgrade, make a note of the node, and then restart via expanding nodes, application, and code restart.

## Error: "Unable to load DLL 'FabricClient.dll'"

If you receive this error, close and restart Windows PowerShell. If the error persists, restart the machine.

## What cluster ID should be used in the agent configuration?

The cluster ID can be any globally unique identifier (GUID). This GUID is used for tracking purposes.

## Encryption errors

Some encryption error examples include AXBootstrapperAppType, Bootstrapper, AXDiagnostics, RTGatewayAppType, Gateway potential failure related, and Microsoft.D365.Gateways.ClusterGateway.exe.

You might receive one of these errors if the data encipherment certificate that was used to encrypt the AOS AccountPassword wasn't installed on the machine. This certificate might be in the certificates (local computer), or the provider type might be incorrect.

To resolve the error, validate the credentials.json file. Verify that the text is decrypted correctly by entering the following command (on AOS1).

Invoke-ServiceFabricDecryptText -CipherText 'longstring' -StoreLocation LocalMachine | Set-Clipboard

This error can also occur if the '' parameter isn't defined in the ApplicationManifest file. To determine whether this parameter is defined, in Event Viewer, go to Custom Views > Administrative Events, and verify the following information:

• The encrypt credentials for the credentials.json file have the correct layout/structure. For more information, see the "Encrypt credentials" section of the appropriate setup and deployment topic for your environment:

• A closing quotation mark appears at the end of the line or on the next line.

• In Event Viewer, under Custom Views > Administrative Events, note any errors in the Microsoft-Service Fabric source category.

## Properties to create a DataEncryption certificate

Use the following properties to create the DataEncryption certificate:

• Is self-signed certificate – Enable this parameter only when you're using self-signed certificates.
• Certificate purposes – Enable all purposes for this certificate.
• Signature algorithm – Specify sha256RSA.
• Signature hash algorithm – Specify sha256.
• Issuer – Specify CN = DataEncryptionCertificate.
• Public Key – Specify RSA (2048 bits).
• Thumbprint algorithm – Specify sha1.

Warning

Don't use self-signed certificates in production environments. Instead, use certificates that are issued by certificate authorities.

## The certificate and private key to use for decryption can't be found (0x8009200C)

If you're missing a certificate and ACL, or if you have the wrong thumbprint entry, check for special characters, and look for thumbprints in C:\ProgramData\SF\<AOSMachineName>\Fabric\work\Applications\AXBootstrapperAppType_App<N>\log\ConfigureCertificates-<timestamp>.txt.

You can also validate the encrypted text by using the following command.

Invoke-ServiceFabricDecryptText -CipherText 'longstring' -StoreLocation LocalMachine | Set-Clipboard

## AddCertToServicePrincipal script fails on Import-Module

Error:

AddCertToServicePrincipal script failing on Import-Module : Could not load file or assembly 'Commands.Common.Graph.RBAC, Version=1.0.0.0, Culture=neutral, PublicKeyToken=31bf3856ad364e35' or one of its dependencies. Strong name validation failed. (Exception from HRESULT: 0x8013141A) may have multiple versions of the same module installed.

Steps: To resolve this issue, follow these steps.

1. Run the following command in Windows PowerShell.
Uninstall-Module -Name AzureRM
Install-Module AzureRM
1. Close the Windows PowerShell window, and try to run the script again.

## ReportingServicesSetup.exe error

Error:

ReportingServicesSetup.exe Error: 0 : Application fabric:/ReportingService is not OK after 10 minutes
Application: ReportingServicesBootstrapper.exe
Framework Version: v4.0.30319
Description: The process was terminated due to an unhandled exception.

Reason: If you receive this error, strong name validation is enabled in the Reporting server, but it should not be enabled.

Steps: To resolve this issue, run the config-PreReq script on the Reporting server machine.

## The requested operation requires elevation

This issue occurs because AOS users aren't in the local administrator group, and User Account Control (UAC) hasn't been disabled correctly. To resolve the issue, follow these steps.

1. Add AOS users as local admins, as described in the "Join VMs to the domain" section of the appropriate setup and deployment topic for your environment:

2. Run the Config-PreReq script on all the AOS machines.

3. Make sure that the Test-Configuration script passes.

4. If UAC was changed, you must restart the machine before the changes take effect.

## Files in use errors

If these errors occur, set up the exclusion rules that are advised by Service Fabric. For information, see Environment setup.

## Apply deployable packages during deployment

### Package deployment fails because of a "path too long" exception

Because of a 260-character limit in Microsoft Windows, deployment will fail if a package has a longer name, or if the on-premises share has the full FQDN path. If the character limit is exceeded, you receive the following error:

System.IO.PathTooLongException: The specified path, file name, or both are too long. The fully qualified file name must be less than 260 characters, and the directory name must be less than 248 characters. at System.IO.PathHelper.GetFullPathName

To work around this issue, shorten the package name, and then apply the package again. Alternatively, shorten the overall length of the share path for the on-premises assets.

### Package deployment fails because of a serialization error

During package deployment, you might receive the following error:

Serialization version mismatch detect, make sure the runtime DLLs are in sync with the deployed metadata. Version of file 'XXX'. Version of DLL 'XXX'

In this case, the version of the environment where the package was developed may differ from the version of the environment that the package is being deployed in.

To work around this issue, keep the development or build environments on the same version as the deployed on-premises environment. You can confirm the package version by looking in the Additional details section in the Asset library where the package is uploaded. To fix the error, generate the package on a version that is the same as or earlier than the version that is deployed on the on-premises environment.

### Package deployment fails because of dependencies on missing modules

If you try to apply a package that is missing dependent modules, package application will fail, and you will receive a message that resembles the following:

To confirm the issue and find the missing dependencies, in Event Viewer, open Application and Services, and then go to Microsoft > Dynamics > AX-SetupModuleEvents to view events that have missing modules. For example, one of the modules that is typically missing is ApplicationFoundationFormAdaptor.

To fix this issue and successfully apply the package, either add dependent modules, or remove modules that require dependent modules. To add dependent modules, you must include the dependencies when you build the package. To remove modules, you can use ModelUtil.exe to delete a module. For more information, see Export and import a model.

### Package deployment works in a one-box environment but not in the sandbox environment

A one-box environment might have all the modules installed, whereas the sandbox environment might have only the modules that are required in order to run your production environment. If the package that was built in the dev environment has a dependency on the modules that are present in the one-box environment but not in the sandbox environment, the package won't work in the sandbox environment.

To resolve this issue, look at all the modules that you're dependent on, and make sure that you don't pull any farm adapter or any other modules that aren't required in the production environment. The best practice is to take the package from the build box.

Platform update 12: Turn off the Skype integration by going to System administration > Setup > Client performance options. When you go to the app, append ?debug=true to the URL, as shown in the following example: https://ax.d365ffo.onprem.contoso.com/namespaces/AXSF/?debug=true

Platform update 8 and Platform update 11: A known Skype application programming interface (API) issue affects the ability to sign in to on-premises environments. We are investigating a resolution for this issue. To work around this issue, you can add ?debug=true to the end of the URL, as shown in the following example: https://ax.d365ffo.onprem.contoso.com/namespaces/AXSF/?debug=true

## The local agent stops working after the tenant for the project from LCS is changed

Follow these steps to configure the local agent with the updated tenant.

1. Uninstall the local agent.

.\LocalAgentCLI.exe Cleanup <path of localagent-config.json>

2. Follow the steps in the "Configure LCS connectivity for the tenant" section of the appropriate setup and deployment topic for your environment:

3. Create a new LCS connector in the new tenant.

5. Install the local agent.

.\LocalAgentCLI.exe Install <path of localagent-config.json>

## Additional deployments (for example, two sandbox deployments, or a sandbox and production deployment)

You will receive the following error when you deploy an additional environment:

.\Publish-ADFSApplicationGroup.ps1 -HostUrl https://ax.d365ffo.onprem.contoso.com New-AdfsApplicationGroup : MSIS9908: The application group identifier must be unique in AD FS configuration.

You can skip or modify the following sections in the deployment instructions.

### Plan and acquire your certificates (as documented for Platform update 12 or Platform update 8 and Platform update 11)

• You must use the same on-premises local agent certificate.
• You can use same star certificates (AOS SSL and Service Fabric).
• The remaining certificates should probably differ from the certificates for the existing environment.

### Download setup scripts from LCS (as documented for Platform update 12 or Platform update 8 and Platform update 11)

• The scripts that are downloaded should be copied into a new folder.

### Set up a standalone Service Fabric cluster (as documented for Platform update 12 or Platform update 8 and Platform update 11)

• The scripts that are downloaded should be copied into a new folder.

### Configure LCS connectivity for the tenant (as documented for Platform update 12 or Platform update 8 and Platform update 11)

• You must complete this task only one time for the tenant.

### Configure AD FS (as documented for Platform update 12 or Platform update 8 and Platform update 11)

• You can skip scripts 1, 2, and 3, because they have already been done.

• The .\Publish-ADFSApplicationGroup.ps1 script will fail even when the new hosturl value is used. Therefore, you must manually complete these steps.

• In AD FS Manager, go to AD FS > Application groups, and open Microsoft Dynamics 365 for Operations On-premises. Then follow these steps:

1. Open the native application Microsoft Dynamics 365 for Operations On-premises - Native application. Add the redirect URI of the new environment (DNS).
2. Open the native application Microsoft Dynamics 365 for Operations On-premises - Financial Reporting - Native application. Add the redirect URI of the new environment (DNS).
3. Open the Web API Microsoft Dynamics 365 for Operations On-premises - Web API. Add the two entries of the redirect URI of the new environment (DNS).
4. Open the Web API Microsoft Dynamics 365 for Operations On-premises - Financial Reporting Web API. Add the redirect URI of the new environment (DNS).

## Redeploy SSRS reports

Delete the entry in SF.SyncLog, and then restart one of the AOS machines. The AOS machine will rerun DB Sync and then deploy reports.

## Add axdbadmin to tempdb after a SQL Server restart via a stored procedure

When SQL Server is restarted, the tempdb database is re-created. As a result, there will be missing permissions. Run the following script to create a stored procedure on the master database.

\-----
USE [master]
GO
CREATE procedure [dbo].[CREATETEMPDBPERMISSIONS] as begin exec ('USE tempdb; declare @dbaccesscount int; select @dbaccesscount = COUNT(*) from master..syslogins where name = ''axdbadmin''; if (@dbaccesscount <> 0) exec sp_grantdbaccess ''axdbadmin''; ALTER USER [axdbadmin] WITH DEFAULT_SCHEMA=dbo; EXEC sp_addrolemember N''db_datareader'', N''axdbadmin''; EXEC sp_addrolemember N''db_datawriter'', N''axdbadmin''; EXEC sp_addrolemember N''db_ddladmin'', N''axdbadmin''; exec sp_grantdbaccess ''contoso\svc-AXSF$''; ALTER USER [contoso\svc-AXSF$] WITH DEFAULT_SCHEMA=dbo; EXEC sp_addrolemember N''db_datareader'', N''contoso\svc-AXSF$''; EXEC sp_addrolemember N''db_datawriter'', N''contoso\svc-AXSF$''; EXEC sp_addrolemember N''db_ddladmin'', N''contoso\svc-AXSF$'';') end GO EXEC sp_procoption N'[dbo].[CREATETEMPDBPERMISSIONS]', 'startup', '1' \----- ## Error: "Updates to existing credential with KeyId '<key>' is not allowed" Update to existing credential with KeyId '<key>' is not allowed. New-AzureRmADSpCredential : Update to existing credential with KeyId '<key>' is not allowed. At C:\InfrastructureScripts\Add-CertToServicePrincipal.ps1:62 char:1 New-AzureRmADSpCredential -ObjectId$servicePrincipal.Id -CertValue \$ ...
CategoryInfo : InvalidOperation: (:) [New-AzureRmADSpCredential], Exception

## ODBC driver 17 required for platform updates

The latest platform binary update uses ODBC driver 17. This upgrade takes care of stability issues linked to older ODBC drivers. The Setup perquisites documentation has been updated to reflect the change in which ODBC driver 17 needs to be installed on each AOS server. If you don't install ODBC driver 17, you will see DB sync errors during servicing of the environment.

Examples of errors:

• In Service Fabric:

Unhealthy event: SourceId='System.RA', Property='ReplicaOpenStatus', HealthState='Warning', ConsiderWarningAsError=false. Replica had multiple failures during open on AOS3. API call: IStatelessServiceInstance.Open(); Error = System.Exception (-2146233088) DB sync failed.

• On AOS machines:

• Event Viewer > Custom Views > Administrative Events:

Application: Microsoft.Dynamics.AX.Deployment.Setup.exe Framework Version: v4.0.30319 Description: The process was terminated due to an unhandled exception. Exception Info: System.IO.FileNotFoundException at Microsoft.Dynamics.AX.Deployment.Setup.Program.Main(System.String[])

• C:\ProgramData\SF\AOSx\Fabric\work\Applications\AXSFType_Appxx\log: Microsoft.Dynamics.AX.Deployment.Setup.exe -bindir "C:\ProgramData\SF\AOS1\Fabric\work\Applications\AXSFType_App18\AXSF.Code.1.0.20180831174152\Packages" -metadatadir "C:\ProgramData\SF\AOS1\Fabric\work\Applications\AXSFType_App18\AXSF.Code.1.0.20180831174152\Packages" -sqluser "axdbadmin" -sqlserver "SQL-LS.contoso.com" -sqldatabase "AXDB" -setupmode servicesync -syncmode fullall -onprem

Unhandled Exception: System.IO.FileNotFoundException: Could not load file or assembly 'aoskernel.dll' or one of its dependencies. The specified module could not be found. at Microsoft.Dynamics.AX.Deployment.Setup.Program.Main(String[] args)

DB sync failed.

## Running Add-CertToServicePrincipal results in “No subscription found in the context”

Recent PowerShell versions may result in "No subscription found in the context" error. Resolution is to install and load an older version of PowerShell. For example, version 5.7.0.

# Install version 5.7.0 of Azure PowerShell
Install-Module -Name AzureRM -RequiredVersion 5.7.0

# Load version 5.7.0 of Azure PowerShell
Import-Module -Name AzureRM -RequiredVersion 5.7.0

## Service Fabric Explorer warnings after restarting machine

Error: Error event: SourceId='MonitoringAgentService', Property='ServiceState'. System.Management.Automation.RuntimeException: Error: The GUID passed was not recognized as valid by a WMI data provider. (Exception from HRESULT: 0x80071068). Stack trace:

To resolve: Restart the application package that generated the warning message. For more information see, Restart applications (such as AOS).

## The internal time zone version number stored in the database is higher than the version supported by the kernel (13/12)

This database sync error can result in deploying old platform build (Platform update 12) on top of a database that had a newer build (Platform update 15).

To resolve this issue, note the SYSTIMEZONESVERSION value:

select * from SQLSYSTEMVARIABLES where parm = 'SYSTIMEZONESVERSION'

Update and set the value to what was returned in the error message:

update SQLSYSTEMVARIABLES set VALUE = 12 where parm = 'SYSTIMEZONESVERSION'

## Printing randomly stops

Ensure that all network printers that have been installed on the AOS server are running as the Windows service account that the AXService.EXE process is running as.

## Ax-DatabaseSynchronize is not being populated with events

In Platform update 20 and later, there is database synchronization log issue where the synchronization logs are not written in the event viewer under Ax-DatabaseSynchronize.

To resolve this issue, go to \AOS_\Fabric\work\Applications\AXSFType_App\log. For example, C:\ProgramData\SF\AOS_11\Fabric\work\Applications\AXSFType_App183\log.

Here you can see the output from DatabaseSynchronize in the Code_AXSF_M_.out files. Troubleshoot any issues regarding this component.

## Unable to access Finance and Operations: AADSTS50058: A silent sign-in request was sent but no user is signed in

This error may occur when logging in to Finance and Operations. After a user enters credentials, the browser will briefly display the application layout, then it will try to redirect outside of Finance and Operations and fail with following error:

AADSTS50058: A silent sign-in request was sent but no user is signed in.

The cookies used to represent the user's session were not sent in the request to Azure AD. This can happen if the user is using Internet Explorer or Edge, and the web app sending the silent sign-in request is in a different IE security zone than the Azure AD endpoint (login.microsoftonline.com).

This happens because there was a change in Skype Presence API and on-premises environments are connecting to it by default.

To resolve the issue, run this SQL Server query: update [AXDB].[dbo].[SYSCLIENTPERF] set SkypeEnabled = 0

-OR-

Turn off the Skype presence enabled option on the Client performance options page (System administration > Setup > Client performance options).

To do this, you must sign in to Finance and Operations. Redirection should be blocked in the browser so that you can sign in and perform that action. After disabling the Skype presence, redirection can be unblocked again.

The Chrome browser blocks redirection by default.

## Error: There was an error during CodePackage activation. Service host failed to activate. Error:0x8007052e

You might receive the following error during a new installation.

Error event: SourceId='System.Hosting', Property='CodePackageActivation:Code:EntryPoint'. There was an error during CodePackage activation.Service host failed to activate. Error:0x8007052e

This will result in the AXSF service also failing with the same error.

To resolve this issue, follow these steps: