Skip to main content
Pentaho Documentation

Troubleshoot Upgrade, Deployment, and Startup Problems


Explains how to resolve common upgrade, deployment, and startup problems.

If you have upgrade or deployment problems, or if PDI does not start, check out the following troubleshooting articles for possible solutions.

Tomcat Logs Report Memory Leaks

When shutting down Tomcat, you may see some SEVERE-level warnings in the log file similar to these:

Dec 17, 2010 10:18:19 AM org.apache.catalina.loader.WebappClassLoader clearReferencesJdbcSEVERE: The web application [/pentaho] registered the JBDC driver [mondrian.olap4j.MondrianOlap4jDriver] but failed to unregister it when the web application was stopped. To prevent a memory leak, the JDBC Driver has been forcibly unregistered.Dec 17, 2010 10:18:19 AM org.apache.catalina.loader.WebappClassLoader clearReferencesThreadsSEVERE: The web application [/pentaho] appears to have started a thread named [HSQLDB Timer @49cf9f] but has failed to stop it. This is very likely to create a memory leak.Dec 17, 2010 10:18:19 AM org.apache.catalina.loader.WebappClassLoader clearReferencesThreadsSEVERE: The web application [/pentaho] appears to have started a thread named [MySQL Statement Cancellation Timer] but has failed to stop it. This is very likely to create a memory leak.Dec 17, 2010 10:18:19 AM org.apache.catalina.loader.WebappClassLoader clearThreadLocalMapSEVERE: The web application [/pentaho] created a ThreadLocal with key of type [java.lang.InheritableThreadLocal] (value [java.lang.InheritableThreadLocal@a1320e]) and a value of type [] (value []) but failed to remove it when the web application was stopped. This is very likely to create a memory leak.

These warnings are nothing to be concerned about when shutting down the Tomcat server, since they report problems with processes that are immanently being killed. However, they can have significance if you are only restarting or redeploying the Pentaho BA Server or DI Server Web applications. To avoid any memory leak problems in redeployment, you should restart Tomcat instead of redeploying or restarting the Web application with a live server.

Library Conflicts

The BA Server relies on many third-party libraries that provide everything from database connectivity to specific Java classes that add necessary features to the BA Server. If you have incompatible versions of any of these third-party libraries in your application server's global lib directory, they can cause a variety of problems related to starting and running the BA Server. You will have to discover and individually canonicalize these files according to your needs.

Some known-problematic JARs are:

  • commons-collections-3.2.jar (from Pentaho)
  • commons-collections.jar (from JBoss in /jboss/server/default/lib/)
  • jettison-1.01.jar (from Pentaho)
  • jettison.jar (from JBoss in /jboss/default/deploy/jbossws.sar)

context.xml Changes Do Not Take Effect After Deploying a WAR


With a manual installation, if you deploy a WAR with a custom context.xml, the context.xml file may not be overwritten.

The location and naming convention for this file are: $CATALINA_HOME/conf/Catalina/<host>/<war name>.xml. Typically this will be something like: /tomcat/conf/Catalina/localhost/pentaho.xml. If this file exists, you will have to delete it prior to deploying the pentaho.war if you have made any changes to context.xml.

vfs-provider.xml Duplicates

The above-referenced configuration file may be present in a number of JARs in other applications that you've deployed to your Java application server. Having multiple instances of this file will cause classpath exceptions. You must merge the multiple files into one canonical edition in order to solve the problem.

javax.jcr.RepositoryException: no search manager configured for this workspace

If you see this error in your PDI server log, then there was an error in the upgrade process from PDI 5.0.0 to 5.1. Specifically, the SearchIndex XML nodes were not properly modified. To fix this, refer to the Upgrading a Data Integration Server piece and closely follow the instructions for modifying repository configuration files.

JBoss Fails to Start When the Pentaho HSQLDB Sample Database Is Running

Note: This problem can also manifest as the Pentaho sample database refusing to start when the BA Server is deployed to JBoss.

The Pentaho-supplied HSQLDB sample database operates on the default HSQLDB port of 9001. JBoss has its own HSQLDB instance running on the same port; therefore, the port collision will prevent the JBoss version from starting, and cause the startup process to halt. You can change the Pentaho sample database port by editing the start_hypersonic script and adding the -port 9002 switch to the last line:

"$_PENTAHO_JAVA" -cp $THE_CLASSPATH org.hsqldb.Server -port 9002 -database.0 $DIR_REL/hsqldb/sampledata -dbname.0 sampledata -database.1 $DIR_REL/hsqldb/hibernate -dbname.1 hibernate -database.2 $DIR_REL/hsqldb/quartz -dbname.2 quartz

JBoss Fails to Start After Manually Unpacking pentaho.war

If you unpack the pentaho.war file by hand, you must name the resultant directory pentaho.war as well.

If you unpack it to any other directory name, including "pentaho" without the .war extension, JBoss will fail to deploy the WAR without any meaningful warnings.

Out of Memory Errors on a VM

If you are installing the DI Server on a VM, and you are trying to deploy on JBoss but, but the DI Server does not start, increase the amount of time that JBoss allows for server deployment.


If you are installing the DI Server on a VM and you are deploying the server on JBoss, you might get out of memory errors. If this happens, the DI Server will not start.  To allot more time for JBoss to deploy DI Server, increase the deployment-timeout variable that is in the JBoss standalone.xml file.  By default, the value is 120 seconds, but you might want to increase it to 240 seconds or longer.

DI Server Does Not Start When Installed on Virtual Machine

If the DI Server does not start when it is installed on a Virtual Machine, and if the DI Server was deployed on the JBoss Web Application Server, increase the amount of time JBoss allows for application deployment.  Increase the deployment time to 240 seconds or longer.  For information on how to do this, see Increase the Amount of Time JBoss Allows for DI Server Deployment.