Version

    10. Troubleshooting

    Since CloverDX Server is considered a universal JEE application running on various application servers, databases and JVM implementations, problems may occur during the installation. These can be solved with a proper configuration of the Server environment. This section contains tips for the configuration.

    Memory Issues on Derby

    JAVA_HOME or JRE_HOME Environment Variables Are Not Defined

    Apache Tomcat Context Parameters Do Not Have Any Effect

    Tomcat Log File catalina.out Is Missing on Windows

    clover.war as Default Context on WebSphere (Windows OS)

    Derby.system.home Cannot be Accessed

    Environment Variables and More than one CloverDX Server Instances Running on Single Machine

    Special Characters and Slashes in Path

    File System Permissions

    JMS API and JMS Third-Party Libraries

    Using an Unsupported JDBC Connector for MySQL

    illegal reflective access warning

    Disabling Session Persistence on Tomcat

    New Resource Caching in Apache Tomcat 8 and Later

    Memory Issues on Derby

    If your Server suddenly starts consuming too much resources (CPU, memory) despite having been working well before, it might be caused by a running internal Derby DB. Typically, causes are incorrect/incomplete shutdown of Apache Tomcat and parallel (re)start of Apache Tomcat.

    Solution: move to a standard (standalone) database.

    How to fix this? Redeploy CloverDX Server:

    1. Stop Apache Tomcat and verify there are no other instances running. If so, kill them.

    2. Backup the configuration file, if you configured any.

    3. Delete the webapps/clover directory.

    4. Start the Apache Tomcat server. It will automatically redeploy CloverDX Server.

    5. Verify you can connect from Designer and from web.

    6. Shutdown Apache Tomcat.

    7. Restore the configuration file and point it to your regular database.

    8. Start Apache Tomcat.

    JAVA_HOME or JRE_HOME Environment Variables Are Not Defined

    If you are getting this error message during an attempt to start your application server (mostly Tomcat), perform the following actions.

    Linux:

    This command sets the path to the variable on the server. [clover@server /] export JAVA_HOME=/usr/local/jdk1.x.x

    Then restart the application server.

    Windows OS:

    Set JAVA_HOME to your JDK installation directory, e.g. C:\Program Files\java\jdk1.8.0.

    JRE or JDK

    Some CloverDX functions requires JDK to work correctly, therefore we do not recommend having only JRE installed.

    Apache Tomcat Context Parameters Do Not Have Any Effect

    Tomcat may sometimes ignore some context parameters. It may cause strange CloverDX Server behavior, since it appears as configured, but only partially. Some parameters are accepted, some are ignored. This issue is rare; however, it may occur in some environments. Such behavior is consistent, so restart has no effect. It’s possibly related to Tomcat issues: Bug #47516 and Bug #50700 To avoid this, configure CloverDX Server using the properties file instead of context parameters.

    Tomcat Log File catalina.out Is Missing on Windows

    Tomcat start batch files for Windows aren’t configured to create the catalina.out file which contains the standard output of the application. The catalina.out file may be vital when Tomcat isn’t started in the console and an issue occurs. Or even when Tomcat is executed in the console, it may be closed automatically just after the error message appears in it.

    Please follow these steps to enable catalina.out creation:

    • Modify [Tomcat_home]/bin/catalina.bat and add the parameter /B to the lines where the _EXECJAVA variable is set. There should be two such lines:

      set _EXECJAVA=start /B [the rest of the line]

      Parameter /B causes the "start" command to not open a new console window, but run in its own console window instead.

    • Create a new startup file, e.g. [Tomcat_home]/bin/startupLog.bat, containing a single line:

      catalina.bat start > ..\logs\catalina.out 2<&1

      It executes Tomcat in the usual way, but the standard output isn’t put to the console, but to the catalina.out file.

    Then use the new startup file instead of [Tomcat_home]/bin/startup.bat.

    clover.war as Default Context on WebSphere (Windows OS)

    If you are deploying clover.war on the IBM WebSphere server without the context path specified, be sure to check whether it is the only application running in the context root. If you cannot start CloverDX Server on WebSphere, check the log and look for a following message:

    com.ibm.ws.webcontainer.exception.WebAppNotLoadedException:
Failed to load webapp: Failed to load webapp: Context root /* is already bound.
Cannot start application CloverDX

    The easiest way to fix the issue is to stop all other (sample) applications and leave only clover.war running on the server. That should guarantee the Server will be available in the context root from now on (e.g. http://localhost:9080/).

    websphere contextRoot
    Figure 9. CloverDX Server as the only running application on IBM WebSphere

    Derby.system.home Cannot be Accessed

    If the Server cannot start and the following message is in the log:

    java.sql.SQLException: Failed to start database 'databases/cloverserver'

    then see the next exception for details. After that, check settings of the derby.system.home system property. It may point to an unaccessible directory, or files may be locked by another process. We suggest you set a specific directory as the system property.

    Environment Variables and More than one CloverDX Server Instances Running on Single Machine

    If you are setting environment variables like clover_license_file or clover_config_file, remember you should not be running more than one CloverDX Server. Therefore, if you ever need to run more instances at once, use other ways of setting parameters (see Configuration for description of all possibilities). The reason is the environment variables are shared by all applications in use causing them to share configurations and fail unexpectedly. Instead of the environment variables, you can use system properties (passed to the application container process using parameter with -D prefix: -Dclover_config_file).

    Special Characters and Slashes in Path

    When working with servers, be sure to follow the folder naming rules. Do not use any special characters in the server path, e.g. spaces, accents, diacritics are not recommended. It can produce issues which are hard to find. If you are experiencing weird errors and cannot trace the source of them, install the application server in a safe destination like:

    C:\JBoss6\

    Similarly, use slashes but never backslashes in paths inside the *.properties files, e.g. when pointing to the CloverDX Server license file. If you incorrectly use a backslash, it will be considered an escape character and the Server may not work properly (this applies to Windows OS, as well). This is an example of a correct path:

    license.file=C:/CloverDX/Server/license.dat

    File System Permissions

    The application server must be executed by an OS user with proper read/write permissions on file system. Problem may occur, if app-server is executed by a root user for the first time, so log and other temp files are created by root user. When the same app-server is executed by another user, it will fail because it cannot write to root’s files.

    JMS API and JMS Third-Party Libraries

    Missing JMS libraries do not cause failure of the Server startup, but it is an issue of deployment on an application server, thus it is still related to this chapter.

    clover.war itself does not contain jms.jar, so it has to be on an application server’s classpath. Most of the application servers have jms.jar by default, but Tomcat, for example, does not. So if the JMS features are needed, the jms.jar has to be added explicitly.

    If the "JMS Task" feature is used, there must be third-party libraries on a Server’s classpath as well. The same approach is recommended for JMS Reader/Writer components, even if these components allow to specify external libraries. It is due to common memory leak in these libraries which causes OutOfMemoryError: PermGen space.

    Using an Unsupported JDBC Connector for MySQL

    CloverDX Server requires MySQL 5 up to version 5.5 included. Using an unsupported JDBC connector for MySQL might cause an exception, for example:

    could not execute query
You have an error in your SQL syntax; check the manual that corresponds to your MySQL server version for the right syntax
to use near 'OPTION SQL_SELECT_LIMIT=DEFAULT' at line 1

    Illegal Reflective Access Warning

    When running CloverDX Server on Java 9 and later, an illegal reflective access warning may occur during startup. For example, below is the warning which appears in the log when Worker is starting:

    [   threadPool-1] WorkerProcess    ERROR     [worker0@node01]1062022167: WARNING: Illegal reflective access by com.sun.xml.bind.v2.runtime.reflect.opt.Injector (file:/home/user/.m2/repository/com/sun/xml/bind/jaxb-impl/2.3.0/jaxb-impl-2.3.0.jar) to method java.lang.ClassLoader.defineClass(java.lang.String,byte[],int,int)

    The warning is caused by changes made in Java 9 and has no effect on the function of CloverDX applications.

    The solution described below applies only to the CloverDX Server + Tomcat 9 bundle. The procedure may differ per application server, so if you run another supported application server and want to suppress the warning, some, all, or a combination of these flags may be required. The changes must be done by your server administrator.

    To disable the warning in CloverDX Server bundle, add the following flags to JDK_JAVA_OPTS in setenv.sh or setenv.bat:

    --add-opens=java.base/java.io=ALL-UNNAMED
--add-opens=java.base/java.lang=ALL-UNNAMED
--add-opens=java.base/java.lang.invoke=ALL-UNNAMED
--add-opens=java.base/java.util=ALL-UNNAMED
--add-opens=java.management/javax.management=ALL-UNNAMED
--add-opens=java.xml/com.sun.org.apache.xerces.internal.dom=ALL-UNNAMED
--add-exports=java.xml/com.sun.org.apache.xerces.internal.parsers=ALL-UNNAMED
--add-opens=java.xml/com.sun.org.apache.xerces.internal.util=ALL-UNNAMED
--add-opens=java.rmi/sun.rmi.transport=ALL-UNNAMED
--add-opens=java.base/sun.net.dns=ALL-UNNAMED
--add-exports=java.base/sun.security.provider=ALL-UNNAMED
--add-exports=java.security.jgss/sun.security.krb5 ALL-UNNAMED

    Disabling Session Persistence on Tomcat

    When using Tomcat, every web application by default has standard manager implementation configured, and it performs session persistence across restarts. However, CloverDX does not support serialization needed to persist. This causes the following error to appear in the catalina.out log:

    Deserialization of HTTP session objects is not supported by CloverDX Server - disable the session passivation/replication for this web application.

    In CloverDX Server bundled with Tomcat, session persistence is disabled by default, but if you are using standalone Tomcat, you should disable session persistence by uncommenting the following line in conf/context.xml:

    <Manager pathname="" />

    New Resource Caching in Apache Tomcat 8 and Later

    In Apache Tomcat 8 and later, new resource caching has been introduced. By default, this caching is enabled with a cache size of 10,240 kB (10 MB) which is not sufficient for CloverDX. It is recommended to increase the cache size by adding the following configuration into context.xml:

    <Resources cachingAllowed="true" cacheMaxSize="20480" />

    Otherwise, the following error occurs:

    WARNING [Final initializer] org.apache.catalina.webresources.Cache.getResource
        Unable to add the resource at [/path/to/file.jar] to the cache for web application [/clover]
        because there was insufficient free space available after evicting expired cache entries - consider increasing the maximum size of the cache