OpenClinica User Manual/OutOfMemoryError

java.lang.OutOfMemoryError: Java heap space edit

If Tomcat reports an internal error that contains the following message

root cause

java.lang.OutOfMemoryError: Java heap space

you can try to increase the maximum java heap size using the JVM



Checking the heap space edit

Before you try to increase the heap space, it is a good plan to check how big it is. You can find this by opening the status-page of Tomcat. But before you can access this page, you must add a user with the tomcat-manager-role to the file tomcat-users.xml This file is located under the Tomcat-directory structure in conf/tomcat-users.xml Add two lines to it:

<role rolename="manager"/>
<user username="tomcat" password="s3cret" roles="manager"/>

Now you can type serveraddress:8080/manager/status or localhost:8080/manager/status in your browser. Tomcat will display a page with statistics about the processes. The line you are looking for is labeled "JVM" and it gives three values:

Free memory, Total memory and Max memory, for example:

Free memory: 48.42 MB Total memory: 61.87 MB Max memory: 123.75 MB

Now we want to increase the heap space to for example 256.

Increasing the heap space: Linux, Tomcat 6 edit

Login to your server. Go to the folder /usr/local/tomcat/bin

Make a safety copy of the shell-script that sets the environment-variables and than start your editor with appropriate rights

sudo -u tomcat cp
sudo -u tomcat vi

Change the line with CATALINA_OPTS to fit your memory-needs, for example:

export JAVA_OPTS="-Xms64m -Xmx256m"

Save the file.

Shutdown Tomcat and startup again.

Browse to server-address:8080/manager/status to check if the changes were applied correctly.

Increasing the heap space: Windows, including Vista, Tomcat 5 and 6, using tomcat5w.exe and tomcat6w.exe edit


  1. Stop Apache tomcat
  2. Go to the Apache tomcat properties by double clicking tomcat5w.exe/tomcat6w.exe (location:Drive (e.g C)/tomact/bin/tomcat5w) or Go to Start>All Programs>Apache Tomcat 5.5>Configure tomcat
  3. Click the Java tab
  4. Under the Java tab set the Initial memory pool and maximum memory pool. These fields by default are empty.
  5. Click Apply then OK
  6. Restart Apache tomcat

In Vista this will only work if you named your service "tomcat6"!

Increasing the heap space: Windows Vista, Tomcat 6, with startup.bat edit

In Windows Vista, if you do not want to start Tomcat as a service, you start and stop Tomcat with two batch-files, located in CATALINA_HOME\bin. Because this batch-file is run as a separate DOS-process, you must set the environment variables involved in Configuration Panel, System, Advanced, System Variables. Look for variable "JAVA_OPTS". If you can't find it, create it. Be careful, because this parameter will affect all other JAVA-apps as well. If you want to increase the heap space just for Tomcat's Catalina, then work with environment-variable CATALINA_OPTS.

If both CATALINA_OPTS and JAVA_OPTS are set, CATALINA_OPTS will be used, even if it's larger than JAVA_OPTS.

Type in the parameter-field "-Xms64m -Xmx256m"

Shutdown Tomcat and startup again. Browse to /manager/status. The line JVM will be something like:

Free memory: 48.44 MB Total memory: 61.87 MB Max memory: 247.50 MB

The parameter Xms defines the initial amount of memory, available for Tomcat, the second parameter, Xmx, the maximum amount of memory.

Another way to do this is using the setenv.bat file. This file is not included in all installations of Tomcat, so you may have to create it. Startup.bat checks some settings and then call catalina.bat, which checks some more and then calls setenv.bat, if it exists. So this is the place to set your CATALINA_OPTS.

Open setenv.bat in a text-editor and put (at least) one line in:

SET CATALINA_OPTS=-Xms64m -Xmx256m

About PermGen edit

Another parameter you can set it the size of PermGen. According to OpenClinica you should allocate about 180m of perm gen per web instance and about 90 megs of memory per Ws instance. [1]

Your settings would look something like

export JAVA_OPTS="-Xms256m -Xmx256m -XX:PermSize=180m"

Additional informations edit

Apache Tomcat 5.5 - Windows service HOW-TO
Apache Tomcat 6.0 - Windows service HOW-TO