Troubleshooting token licensing problems

Find information to help resolve issues that you might encounter with token licensing if you activated this feature when you installed MobileFirst Server.

When you start the MobileFirst Server administration service after you complete Installing and configuring for token licensing, some errors or exceptions can be emitted in the application server log or on MobileFirst Operations Console. These exceptions might be due to incorrect installation of the Rational Common Licensing library and configuration of the application server.

Apache Tomcat: Check catalina.log or catalina.out file, depending on your platform.
WebSphere® Application Server Liberty profile: Check messages.log file.
WebSphere Application Server full profile: Check SystemOut.log file.

Important: If token licensing is installed on WebSphere Application Server Network Deployment or a cluster, you must check the log of each server.

Here is a list of exceptions that might occur after the installation and configuration for token licensing:

Rational Common Licensing native library is not found

FWLSE3125E: The Rational Common Licensing native library is not found. Make sure the JVM property (java.library.path) is defined with the right path and the native library can be executed. Restart IBM MobileFirst Platform Server after taking corrective action.

For WebSphere Application Server full profile

Possible causes to this error might be:

No common property with name java.library.path is defined at server level.
The path that is given as the value for the java.library.path property does not contain the Rational Common Licensing native library.
The native library does not have appropriate permissions. The library must have the read and execute privileges on UNIX and Windows for the user who accesses it with the Java™ Runtime Environment of the application server.

For WebSphere Application Server Liberty profile and Apache Tomcat

Possible causes to this error might be:

The path to the Rational Common Licensing native library given as the value of java.library.path property is either not set or incorrect.
- For Liberty profile, check ${wlp.user.dir}/servers/server_name/jvm.options file.
- For Apache Tomcat, check ${CATALINA_HOME}/bin/setenv.bat file or setenv.sh file, depending on your platform.
The native library is not found in the path that is defined to the java.library.path property. Check that the native library exists in the defined path with the expected name.
The native library does not have appropriate permissions. The error might be preceded by this exception: com.ibm.rcl.ibmratl.LicenseConfigurationException: java.lang.UnsatisfiedLinkError: {0}\rcl_ibmratl.dll: Access is denied
The Java Runtime Environment of the application server needs read and execute privileges on this native library. The library file must also be readable and executable at least for the application server process in your operating system.
The shared library that uses the rcl_ibmratl.jar file is not defined in the ${server.config.dir}/server.xml file for Liberty profile. The rcl_ibmratl.jar might also not in the correct directory or the directory does not have the appropriate permissions.
The shared library that used the rcl_ibmratl.jar file is not declared as a common library for the MobileFirst Server administration service application in the ${server.config.dir}/server.xml file for the Liberty profile.
There is a mix of 32-bit and 64-bit objects between the Java Runtime Environment of the application server and the native library. For example, a 32-bit Java Runtime Environment is used with a 64-bit native library. This mix is not supported.

Rational Common Licensing shared library is not found

FWLSE3126E: The Rational Common Licensing shared library is not found. Make sure the shared library is configured. Restart IBM MobileFirst Platform Server after taking corrective action.

Possible causes to this error might be:

The rcl_ibmratl.jar file is not in the expected directory.
- For Apache Tomcat, check that this file is in ${CATALINA_HOME}/lib directory.
- For WebSphere Application Server Liberty profile, check that this file is in the directory as defined in the server.xml file for the shared library of the Rational Common Licensing client. For example, ${shared.resource.dir}/rcllib. In the server.xml file, ensure that this shared library is correctly referenced as a common library for MobileFirst Server administration service application.
- For WebSphere Application Server, make sure that this file is in the directory that is specified in the class path of the WebSphere Application Server shared library. Check that the class path of that shared library contains this entry: absolute_path/rcl_ibmratl.jar whereas absolute_path is the absolute path of the rcl_ibmratl.jar file.
The java.library.path property is not set for the application server. Define a property with name java.library.path and set the path to the Rational Common Licensing native library as the value. For example, /opt/IBM/RCL_Native_Library/.
The native library does not have the expected permissions. On Windows, the Java Runtime Environment of the application server must have the read and executable rights on the native library.
There is a mix of 32-bit and 64-bit objects between the Java Runtime Environment of the application server and the native library. For example, a 32-bit Java Runtime Environment is used with a 64-bit native library. This mix is not supported.

The Rational License Key Server connection is not configured

FWLSE3127E: The Rational License Key Server connection is not configured. Make sure the admin JNDI properties "mfp.admin.license.key.server.host" and "mfp.admin.license.key.server.port" are set. Restart IBM MobileFirst Platform Server after taking corrective action.

Possible causes to this error might be:

The Rational Common Licensing native library and the shared library that uses the rcl_ibmratl.jar file are correctly configured but the value of JNDI properties (mfp.admin.license.key.server.host and mfp.admin.license.key.server.port) is not set in the MobileFirst Server administration service application.
The Rational License Key Server is down.
The host computer on which Rational License Key Server is installed cannot be reached. Check the IP address or host name with the specified port.

The Rational License Key Server is not accessible

FWLSE3128E: The Rational License Key Server "{port}@{IP address or hostname}" is not accessible. Make sure that license server is running and accessible to IBM MobileFirst Platform Server. If this error occurs at runtime startup, restart IBM MobileFirst Platform Server after taking corrective action.

Possible causes to this error might be:

The Rational Common Licensing shared library and the native library are correctly defined but there is no valid configuration to connect to the Rational License Key Server. Check the IP address, the host name, and the port of the license server. Make sure that the license server is started and accessible from the computer where the application server is installed.
The native library is not found in the path that is defined to the java.library.path property.
The native library does not have appropriate permissions.
The native library is not in the defined directory.
The Rational License Key Server is behind a firewall. The error might be preceded by this exception: [ERROR] Failed to get license for application 'WorklightStarter' because Rational Licence Key Server ({port}@{IP address or hostname}) is either down or not accessible com.ibm.rcl.ibmratl.LicenseServerUnreachableException. All license files searched for features: {port}@{IP address or hostname}
Ensure that the license manager daemon (lmgrd) port and the vendor daemon (ibmratl) port are open in your firewall. For more information, see How to serve a license key to client machines through a firewall.

Failed to initialize Rational Common Licensing API

Failed to initialize Rational Common Licensing (RCL) API because its native library could not be found or loaded com.ibm.rcl.ibmratl.LicenseConfigurationException: java.lang.UnsatisfiedLinkError: rcl_ibmratl (Not found in java.library.path)

Possible causes to this error might be:

The Rational Common Licensing native library is not found in the path that is defined to the java.library.path property. Check that the native library exists in the defined path with the expected name.
The java.library.path property is not set for the application server. Define a property with name java.library.path and set the path to the Rational Common Licensing native library as the value. For example, /opt/IBM/RCL_Native_Library/.
There is a mix of 32-bit and 64-bit objects between the Java Runtime Environment of the application server and the native library. For example, a 32-bit Java Runtime Environment is used with a 64-bit native library. This mix is not supported.

Insufficient token licenses

FWLSE3129E: Insufficient token licenses for feature "{0}".

This error occurs when the remaining number of token licenses on the Rational License Key Server is not enough to deploy a new MobileFirst application.

Invalid rcl_ibmratl.jar file

UTLS0002E: The shared library RCL Shared Library contains a classpath entry which does not resolve to a valid jar file, the library jar file is expected to be found at {0}/rcl_ibmratl.jar.

Note: For WebSphere Application Server and WebSphere Application Server Network Deployment only

Possible causes to this error might be:

The rcl_ibmratl.jar Java library does not have the appropriate permissions. The error might be followed by another exception: java.util.zip.ZipException: error in opening zip file.
Check that the rcl_ibmratl.jar file has the read permission for the user who installs WebSphere Application Server.
If there is no other exception, the rcl_ibmratl.jar file that is referenced in the class path of the shared library might be invalid or does not exist. Check that the rcl_ibmratl.jar file is valid or exists in the defined path.