Troubleshooting

Typically, an upgrade completes with few hiccups and the new version of Keyfactor Command comes up without incident. If this doesn’t happen, start by checking the log file(s) for any errors. By default, these are located in C:\Keyfactor\logs. It is sometimes helpful to enable debug or trace level logging. This is done by editing the nlog.config file for each application. For more information, see Editing NLog in the Keyfactor Command Reference Guide.

If you encounter an error during upgrade, this can be the result of a number of different things. Often, it's related to connectivity to SQL or issues on the SQL server. Check the Command_Configuration_Log.txt for messages related to upgrading and upgrade failures. This will point you in the right direction to begin troubleshooting.

The following error message indicates that the referenced upgrade script failed because it took longer to run than the allowed limit for SQL tasks:

2022-12-07 10:19:07.5078 Keyfactor.Sql.Management.Upgrade.UpgradePlan [Error] - Failed to run upgrade module CSS.CMS.Install.Upgrade.Scripts.EJBCA_Resolved_Request_Contents_Removal.sql: Execution Timeout Expired. The timeout period elapsed prior to completion of the operation or the server is not responding.

The Keyfactor Command upgrade process includes multiple scripts, each doing different tasks, and each script is run in batches to limit the time and load of any one SQL request, but it's still possible to encounter a batch that exceeds the limit with vary large or complex databases. To resolve this particular issue, you can increase the timeout limit and restart the upgrade. You do not need to restore and start over.

To increase the timeout limit:

  1. On the Keyfactor Command server, open a text editor (e.g. Notepad) using the “Run as administrator” option.

  2. In the text editor, browse to open the CSS.CMS.Install.ConfigurationWizard.exe.config file (ConfigurationWizardConsole.exe.config if you're doing a command-line install) in the Configuration directory under the installed directory. By default, this is:

    C:\Program Files\Keyfactor\Keyfactor Platform\Configuration\CSS.CMS.Install.ConfigurationWizard.exe.config

  3. Locate the appSettings line that contains Keyfactor.Sql.DbCommandTimeout. This will look something like:

    <add key="Keyfactor.Sql.DbCommandTimeout" value="1800" />
  4. The timeout value is set in seconds, so the default of 1800 seconds is 30 minutes. Set it to a new, longer value to allow the upgrade to complete. Don't set it to a value that's too high, as you do want the upgrade to time out if there's some fundamental problem communicating with SQL.
  5. Save the file, close the configuration wizard, open the configuration wizard again (you should find it on the menu), and begin the upgrade again.

Figure 618: Error During Upgrade

Note:  In previous versions of Keyfactor Command, the timeout was controlled with the command timeout setting in the connection string of the SharedSqlConnectionStrings.config file and had a default of 360 seconds (6 minutes).

If the Keyfactor Command Management Portal appears to partially load or does not appear to include expected updates after the upgrade, try clearing the browser cache, closing the browser, and opening a fresh browser session. Try using CTRL-F5 to request the page again without cached content. In some upgrade cases, with Internet Explorer, the Certificate Search page only partially loads. With some browsers, opening the Developer Tools with the F12 key and clearing the cache will resolve the problem.

If the certificate enrollmentClosed Certificate enrollment refers to the process by which a user requests a digital certificate. The user must submit the request to a certificate authority (CA). fails, this is often an indication that there is a Kerberos authentication problem. Confirm that the service principal name (SPN) is set correctly for the application pool service account and that Kerberos constrained delegation is configured correctly from the Keyfactor Command server(s) to the CAClosed A certificate authority (CA) is an entity that issues digital certificates. Within Keyfactor Command, a CA may be a Microsoft CA or a Keyfactor gateway to a cloud-based or remote CA.(s). For more information, see Configure Kerberos Authentication in the Keyfactor Command Server Installation Guide.

If your alert PowerShell event handlers or renewal event handlers do not run correctly, be sure that you have updated them to the correct new location. Scripted alert handlers will fail to run if not in the path (or a subdirectory of it) specified by the Extension Handler Path application setting. By default, this is C:\Program Files\Keyfactor\Keyfactor Platform\ExtensionLibrary\. For more information, see Adding PowerShell Handlers to Alerts in the Keyfactor Command Reference Guide.

If you receive a 500 error loading the dashboard and running reports but the remainder of the Management Portal seems to be operating correctly, check to be sure that the IP address(es) configured in the Configuration Wizard on the Dashboard and Reports tab have been entered correctly.

If you receive an error when opening the Management Portal that “the underlying connection was closed” please be sure you have all the latest Windows updates installed.

Please refer to the Keyfactor Command Release Notes for known issues (see Keyfactor Command Release Notes).

If you need further assistance, please contact support. During normal business hours, support can be reached at support@keyfactor.com or (877)-715-5448.