Skip to main content
Kofax

Installation of KCM fails with the warning that the instance registration failed

  1. Last updated
  2. Save as PDF
Article # 3035807 - Page views: 92

Issue

The installation of KCM 5.5 completes with the following warning 

Registering instance on the contract manager.
Instance registration failed due to: An error occurred. The error was logged under error id {181152d3-6627-494d-b776-3d1a11ce5868}.
Please register the instance on the contract manager manually.
Install.exe succeeded

The example web application (http://localhost:8081/start/home.html / https://localhost/start/home.html) is not available after installation succeeded with the above warning. 

 

Cause

When the contract manager is not available, the instance cannot be registered at the contract manager. This is also required for adding the example web application. 
This error occurs if the contract manager is not reachable. This can happen if the port used by the Contract Manager is already in use.
For HTTP the used port is 8081 (ContractManager!UseSSL=False).
For HTTPS the used port is 443 (ContractManager!UseSSL=True). 
If HTTPS is used, then this error can also occur when the password for the certificate is incorrect. 

 

Solution

The port is already in use and the port can be made available

To confirm if the port is already in use, consult the Tomcat catalina log file. The default location is:
   <Tomcat>\instance-KCMRuntime-5.5\logs\catalina.<date>.log. 
For example:

"C:\Program Files\Apache Software Foundation\Tomcat 9.0\instance-KCMRuntime-5.5\logs\catalina.2021-08-24.log"
If port 8081 is already in use, then the following log line is logged:
24-Aug-2021 09:08:04.994 INFO [main] org.apache.coyote.AbstractProtocol.init Initializing ProtocolHandler ["http-nio-8081"]
24-Aug-2021 09:08:05.024 SEVERE [main] org.apache.catalina.util.LifecycleBase.handleSubClassException Failed to initialize component [Connector[HTTP/1.1-8081]]
...
    Caused by: java.net.BindException: Address already in use: bind

    
To resolve this issue:

  1. Open command prompt and navigate to ..\KCM\Programs\<version>\Management\Instance
  2. run the command
    StopInstance.exe instance!number=1
  3. Make port 8081 (HTTP) or port 443 (HTTPS) available again. To locate the external program that already claims the port 8081/443 the Windows command line tool netstat can be used. Run from elevated command prompt

       netstat -anb > C:\temp\netstat.txt

    This will write to C:\temp\netstat.txt, all programs that use network ports. E.g. this shows that port 8282 is used by the process tomcat9.exe.

     TCP  0.0.0.0:8282      0.0.0.0:0       LISTENING    10084
     [Tomcat9.exe]

    Note: In the case of the process name "Can not obtain ownership information" it is normally IIS that has the port in use.
  4. Restart the service "Apache Tomcat KCMRuntime-5.5"
  5. Open command prompt and navigate to ..\KCM\Programs\<version>\Management\Instance
  6. run the command
    StartInstance.exe instance!number=1
The port is already in use and the port cannot be made available

In some situations it is not possible to make the port available. For example McAfee endpoint security requires the use of port 8081. If this software program is used, then it is not possible to use KCM with HTTP on port 8081 as it is already in use by McAfee endpoint security. If it is not possible to make port 8081 available, then it is an option to switch to HTTPS (port 443). Vice versa it is also possible to switch from HTTPS (port 443) to HTTP (port 8081). 

To confirm if the port is already in use, consult the Tomcat catalina log file. The default location is:
   <Tomcat>\instance-KCMRuntime-5.5\logs\catalina.<date>.log. 
For example:

"C:\Program Files\Apache Software Foundation\Tomcat 9.0\instance-KCMRuntime-5.5\logs\catalina.2021-08-24.log"
If port 8081 is already in use, then the following log line is logged:
24-Aug-2021 09:08:04.994 INFO [main] org.apache.coyote.AbstractProtocol.init Initializing ProtocolHandler ["http-nio-8081"]
24-Aug-2021 09:08:05.024 SEVERE [main] org.apache.catalina.util.LifecycleBase.handleSubClassException Failed to initialize component [Connector[HTTP/1.1-8081]]
...
    Caused by: java.net.BindException: Address already in use: bind
  1. Open command prompt and navigate to ..\KCM\Programs\<version>\Management\Instance\
  2. run the command
    StopInstance.exe instance!number=1
  3. Navigate to ..\KCM\Programs\<version>\Management\Contract Manager\
  4. run the command
    StopContractManager.exe
  5. To switch from HTTP (port 8081) to HTTPS (port 443)
    run the command
    SetContractManagerConnection.exe ContractManager!UseSSL=true ContractManager!keystorefile="path\to\certificate.pfx ContractManager!keystorepassword=password
    where ContractManager!keystorefile is the path to the certificate file and ContractManager!keystorepassword is the password for the certificate.

    To switch from HTTPS (port 443) to HTTP (port 8081)
    run the command
    SetContractManagerConnection.exe ContractManager!UseSSL=false 
  6. run the command
    StartContractManager.exe
  7. Navigate to ..\KCM\Programs\<version>\Management\Instance\
  8. run the command
    StartInstance.exe instance!number=1
The certificate password is incorrect

When HTTPS is used, it is possible that the wrong password was specified for the certificate. To confirm if the password was incorrectly entered, consult the Tomcat catalina log file. 
   <Tomcat>\instance-KCMRuntime-5.5\logs\catalina.<date>.log. 
For example:

"C:\Program Files\Apache Software Foundation\Tomcat 9.0\instance-KCMRuntime-5.5\logs\catalina.2021-08-24.log"
In case of an incorrect password for the certificate the following lines are logged:
24-Aug-2021 10:58:58.598 SEVERE [main] org.apache.catalina.util.LifecycleBase.handleSubClassException Failed to initialize component [Connector[HTTP/1.1-443]]
    org.apache.catalina.LifecycleException: Protocol handler initialization failed
...    
    Caused by: java.lang.IllegalArgumentException: keystore password was incorrect
  1. Open command prompt and navigate to ..\KCM\Programs\<version>\Management\Instance\
  2. run the command
    StopInstance.exe instance!number=1
  3. Navigate to ..\KCM\Programs\<version>\Management\Contract Manager\
  4. run the command
    StopContractManager.exe
  5. run the command
    SetContractManagerConnection.exe ContractManager!UseSSL=true ContractManager!keystorefile="path\to\certificate.pfx ContractManager!keystorepassword=password
    where ContractManager!keystorefile is the path to the certificate file and ContractManager!keystorepassword is the password for the certificate.
  6. run the command
    StartContractManager.exe
  7. Navigate to ..\KCM\Programs\<version>\Management\Instance\
  8. run the command
    StartInstance.exe instance!number=1

 

Level of Complexity 

High

 

Applies to  

Product Version Build Environment Hardware
Kofax Communications Manager 5.5 n/a n/a n/a

 

 

Article # 3035807
  1. Back to top
  • Was this article helpful?

Recommended articles

  1. Article type
    Topic
  2. Tags
    This page has no tags.