These are common issues that you may encounter during system installation or use. If you are upgrading on or to the 5.6 branch, please see also Upgrading to Magnolia 5.6.x

Performance issues

For details please see the Performance issues subpage.

H2 database

We don't recommend using H2 database for production environments.

By default, the H2 database is not used anywhere directly. It is only accessed through JCR and JackRabbit APIs and it is embedded within a JVM running Magnolia without being open to outside access, thus offering nearly no opportunity for a potential attacker to exploit it.

H2 database issues in versions 1.4.199 and 1.4.200

Magnolia releases 5.5.16, 5.6.13, 5.7.6 and 6.1.3 came with H2 database update from version 1.4.192 to 1.4.199 due to a known security issue. Unfortunately, it was found out later on that version 1.4.199 is suffering from a consistency issue ( and while a fix for it has been released with H2 1.4.200, this version introduces another issue (, which may affect the structure of tables and the ability of H2 to read previously stored data.

To keep your systems and data secure, we recommend that you consider taking the following measures:

  • Avoid using H2 in version 1.4.199, the main source of the issues.

  • If you are still running version 1.4.192, don't upgrade to any of the maintenance releases mentioned, that is 5.5.16, 5.6.13, 5.7.6 or 6.1.3, depending on which Magnolia branch you are using.
    Wait for the next maintenance release that will ship with a version higher than 1.4.199. Since the 5.5 Magnolia branch has reached End of Life, migrate to a higher branch. Currently, there are no additional maintenance releases planned for the 5.5 branch.

    Additionally, ensure that the H2 database is not exposed through your custom code modifications. Your installation will then not be affected by the uncovered security issue. Especially, please ensure that the DB is not exposed via your custom code modifications, for example by accessing the DB directly and exposing a query or by other payload going to it through your application directly. If you adhere to these recommendations, your installation will not be affected by the security issue.

  • If you have already upgraded to 1.4.199, downgrading is not possible due to upstream data structure changes that are incompatible with previous versions. Try updating to version 1.4.200 and see if you experience any issues. If you do come across some issues after the upgrade, contact our support.

  • If you are using H2 only in development, you can:

    • Delete the local database and downgrade to version 1.4.192.
    • Switch to another database, for example Derby, and reinstall your local installation.

H2 does not accept more than one connection

Our default configuration uses the server mode for H2. If you migrate from Magnolia below 5.5.9 in the 5.5 branch or below 5.6.2 in the 5.6 branch and try to initiate a backup call using CLI or REST, it fails because H2 does not allow more than one connection at a time. Configure H2 to run in server mode by adding AUTO_SERVER=TRUE in the URL parameters: 

<param name="url" value="jdbc:h2:${wsp.home}/db;AUTO_SERVER=TRUE" />

<param name="url" value="jdbc:h2:${rep.home}/version/db;AUTO_SERVER=TRUE" />

See  MAGNOLIA-7227 - Getting issue details... STATUS

Reloading a page in the editor causes a 404 error

When you open a page for editing and reload it in the browser, an extra semicolon is added to the URL fragment and the server returns a 404 error. Every subsequent reload adds another semicolon. This issue occurs with older versions of the Tomcat application server. To resolve this issue, upgrade to Tomcat 7.0.47+. See  MGNLUI-2426 - Getting issue details... STATUS

Tomcat 7.0.66+ Trailing slash issue

When accessing the webapp without the trailing slash after the context http://localhost:8080/magnoliaAuthor after login the user is presented with a 404 page rather than admincentral.  This behavior is configurable via the mapperContextRootRedirectEnabled and mapperDirectoryRedirectEnabled attributes of the Context which may be used to restore the previous behavior. See Apache Tomcat 7 Changelog.

Oracle WebLogic 10 conflict with commons-lang library

When deploying on Oracle WebLogic 10, there is a version conflict while using commons-lang. While Oracle WebLogic-10 is distributed with commons-lang-2.3.jar, JackRabbit and Magnolia need at least commons-lang-2.4.jar. To resolve this issue, modify of Oracle WebLogic and add commons-lang-2.4.jar to the PRE_CLASSPATH. Since version 2.4 commons-lang doesn't remove any methods, but only adds new API and fixes known bugs, there is no adverse effect from this change to the Oracle WebLogic installation.

Oracle WebLogic 12c conflict with Bouncy Castle library

Magnolia uses the Bouncy Castle cryptography package to decode the license key and to secure the activation process. Oracle WebLogic 12c is distributed with bcprov-jdk16-1.45.jar but Magnolia is distributed with bcprov-jdk16-1.46.jar. This leads to a library version conflict.

Symptom: after inserting valid license key into the Magnolia license form, the error message "License is empty" is displayed.

To resolve, do one of the following:

  • Edit in Oracle WebLogic and add bcprov-jdk16-1.46.jar to PRE_CLASSPATH or
  • Remove bcprov-jdk16-1.45.jar from Oracle WebLogic 12c common libraries.

Oracle WebLogic and IBM WebSphere deployment issue with jBPM 6

jBPM 6 cannot be deployed on Oracle WebLogic or IBM WebSphere. jBPM is included in the Magnolia Workflow module. All deployment methods are affected: Administration Console, Oracle WebLogic.Deployer, wldeploy Ant task and autodeploy directory.


weblogic.application.ModuleException: java.lang.ClassNotFoundException:


  1. Deploy an application which doesn't contain Magnolia Workflow with jBPM6, for example Magnolia 5.2.2 or Magnolia 5.3 without the Workflow module.
  2. In the deployment target location, replace the deployed webapp with a new webapp that contains workflow with jBPM6

Oracle WebLogic 12c conflict with Google Guava library

Magnolia cannot render images stored in dam workspace. Google Guava library is used by the DAM API 2.0 which is used for working with images.


java.lang.RuntimeException: java.lang.NoClassDefFoundError: Could not initialize class


 Modify the weblogic.xml file in your application's WEB-INF folder with the prefer-application-packages  element:


Jetty 9± stream closed

Magnolia's resource loader makes heavy use of accessing classpath resources (last modification date and contents). Jetty uses caching of such resources by default, which may result in a occurring randomly. See MAGNOLIA-6860 - Getting issue details... STATUS .

Mac OS X 10.5 - Leopard

If you use Mac OS X 10.5 or 10.6, you should update to at least 10.5.8 or 10.6.2. Earlier versions cause issues where, when two or more instances are started in the same container, some or all connections are dropped.

The symptoms are that Tomcat is unreachable ("kCFErrorDomainCFNetwork:302") but no log message clearly identifies the issue. Sometimes pages can be loaded but resources cannot, leading to missing images or stylesheets. Another symptom is that you have to kill the Tomcat process to stop it (-HUP works) because the shutdown script cannot reach the running process either. See MAGNOLIA-1959 for more details and comment on your own experience.

Too many open files

The embedded Derby database that Magnolia uses for demonstration opens several file handles and may run over the maximum limit set by the system. This issue can occur on some Linux and OS X systems such as Macbook Air.

The solution is to increase the system-wide limit on the number of open files. The exact procedure varies from one OS to the next, see Too many open files.

  1. Find the current maximum number of open files per user in a single session: 
    ulimit -n
    By default the number is 1024 which is too small.
  2. Edit the limits.conf file: 
    sudo gedit /etc/security/limits.conf
  3. Add the following lines to the file: 
    * soft nofile 10000
    * hard nofile 50000
    This sets for all users a soft limit of 10000 open files and a hard limit of 50000. These are just example numbers. Set them according to your system needs. Note that the wildcard option applies only to regular users, not to superuser. If you run Magnolia as superuser replace the asterisk with root.
  4. Save the file.
  5. Edit the configuration file for session-related modules: 
    sudo gedit /etc/pam.d/common-session
  6. Add the following line to the file: 
    session required

    On *ubuntu 17.04 you'll probably also have to add the following line


    to /etc/systemd/system.conf

    and to /etc/systemd/user.conf .

    See Cannot Increase open file limit past 4096 (Ubuntu).

  7. Save the file.
  8. Restart Ubuntu.
  9. Verify the new maximum number of open files: 
    ulimit -n
    The command should now return 10000.

OS X 10.8 Mountain Lion:

  1. Find the current maximum number of open files per user in a single session: 
    ulimit -n
    By default the number is 256 which is too small.
  2. Add ulimit -n 65536 to your ~/.profile file. This increases the limit for the shell.
  3. Create a file /etc/sysctl.conf if it doesn't exist.
  4. Add the following lines in /etc/sysctl.conf. This increases the limit for the kernel.
  5. Open a terminal and type:

    sudo sysctl -w kern.maxfiles=65536
    sudo sysctl -w kern.maxfilesperproc=65536
    sudo ulimit -n 65536

    -- OR --
    Restart OSX to read the settings from the files you edited.

  6. Type ulimit -n. The response should be 65536. (If not, restart OSX)
  7. Install Magnolia

OS X 10.9 (Mavericks), 10.10 (Yosemite) and 10.11 (El Capitan), see Shell Session Limit

OS X 10.12 (Sierra) and 10.13 (High Sierra), see the answer given for For OS X Sierra (10.12.X) on this page.

Session de-serialization

When installing or updating to a new version, you may see this error message:

2009-11-24 13:02:14,970 ERROR org.apache.catalina.session.ManagerBase : 
IOException while loading persisted sessions

This can be due to changes in signatures of classes that are stored in user sessions, such as permissions, user, etc. The error happens when Tomcat attempts to de-serialize serialized sessions as the container starts. The de-serialization causes the loss of persisted sessions. Users will have to log in again. Otherwise it is a harmless error and can be ignored.


If you see the following error message in your logs:

Provider org.apache.xalan.processor.TransformerFactoryImpl not found

Add the Xalan jar to the WEB-INF/lib folder of your Magnolia instances, delete the repositories and start again. Please see MAGNOLIA-1958 for more details and comment on your own experience.

Port 8080 is already in use

Port 8080 is the default port for Tomcat. You can see it at the end of the default address http://localhost:8080. If another application on the computer is already using the same port, you may need to change it.

  1. Open <CATALINA_HOME>/conf/server.xml in a text editor. This file is under your Magnolia installation directory.
  2. Find the following section and set the value of port to something other than 8080, for example 8090:

    <!-- Define a non-SSL HTTP/1.1 Connector on port 8080 -->
    <Connector port="8090" maxHttpHeaderSize="8192"
               maxThreads="150" minSpareThreads="25" maxSpareThreads="75"
               enableLookups="false" redirectPort="8443" acceptCount="100"
               connectionTimeout="20000" disableUploadTimeout="true" />

Change the defaultBaseUrl property, which is used to create absolute links in emails or other external systems. To do this, you need to now access Magnolia at the new port 8090.

  1. Log into the author instance at http://localhost:8090/magnoliaAuthor/.magnolia.
  2. Go to Configuration.
  3. Set the value of /server/defaultBaseUrl property to http://localhost:8090/magnolia/.
  4. Log into the public instance at http://localhost:8090/magnoliaPublic/.magnolia.
  5. Go to Configuration.
  6. Set the value of /server/defaultBaseUrl property to http://localhost:8090/magnolia/.

Now the Welcome page at http://localhost:8090 has the correct URLs too.

The port also needs to be changed in publishing configuration, otherwise publishing (activating) changes from the author to public instance fails.

  1. On the author instance, 
    1. If you are using the Publishing module, go to Configuration > modules > publishing-core > config > receivers .
    2. If you are using the Activation module, go to Configuration > modules > activation > subscribers .
  2. Under the magnoliaPublic8080 receiver (subscriber), set the URL property to http://localhost:8090/magnoliaPublic.
  3. Rename the receiver (subscriber) to magnoliaPublic8090.
  4. Activate the modified receiver (subscriber) including its subnodes.

If you want to run two different Tomcats simultaneously you need to change other ports too. This is useful if you want to run different versions of Magnolia at the same time. In <CATALINA_HOME>/conf/server.xml, change the port numbers for the shutdown and AJP sections and any custom sections you have enabled.

JVM issues on Windows

32-bit JVM does not work in Windows

((info) Tested on Windows 10.) When starting up Tomcat with the Magnolia CLI mgnl start command, you get a flickering window, the server hangs and nothing is written into the logs. To see the actual error, don't use Magnolia CLI to start Magnolia, start Tomcat directly with <your-magnolia-install-folder>\apache tomcat\bin\catalina.bat run. This should start Magnolia in the same window and allow you to see the error message:

Error occurred during initialization of VM
Could not reserve enough space for 2097152KB object heap

The most likely cause is that you are trying to allocate too much heap space in the 32-bit JVM. 

Solution: Replace the JVM with a 64-bit version.

See also: Why can't I get a larger heap with the 32-bit JVM?

Neither JAVA_HOME nor JRE_HOME is defined

You get the following error message after a fresh Java installation:

Neither the JAVA_HOME nor the JRE_HOME environment variable is defined
At least one of these environment variables is needed to run this program

Solution: Set the variables through the "Edit the system environment variables" dialog.

JRE_HOME is undefined

If you get an error like this one:

The JRE_HOME environment variable is not defined correctly
The environment variable is needed to run this program

then you are most probably attempting to run Tomcat with the JAVA_HOME variable set but without the JRE_HOME variable defined.

Solution: Set the JRE_HOME variable.

Windows Firewall is blocking Java

Allow an exception in Windows Firewall for Java.

  1. Go to Control Panel > Windows Firewall.
  2. Go to the Exceptions tab.
  3. Click Add Program and browse to the java.exe file in the Java installation directory, for example C:\Sun\SDK\jdk\bin\java.exe.
  4. Click OK.

If you get a security alert during startup, check the Private networks checkbox and click Allow access.

CATALINA_HOME environment variable is not defined

CATALINA_HOME environment variable identifies the Tomcat home directory, for example C:\Program Files\magnolia\apache-tomcat. Usually Magnolia finds this directory automatically. When you type magnolia_control.bat start in the bin directory to start the system, a second script named startup.bat tries to find Tomcat home. It assumes that Tomcat home is one level above the bin directory where you issued the command, and sets the value of CATALINA_HOME to that directory.

C:\Program Files
        apache-tomcat   <-- Tomcat home directory
            bin         <-- magnolia_control.bat is here

However, if you added the bin directory to your PATH environment variable you can execute magnolia_control.bat from anywhere. This means startup.bat does not find Tomcat home directory by simply moving up one level from where you are and displays the following error:

To correct this define CATALINA_HOME in environment variables. Follow the instructions in Set JAVA_HOME environment variable.

Java out of memory

If the Java Virtual Machine (JVM) does not have enough memory you may see a java.lang.OutOfMemoryError  in the startup log and Magnolia fails to start.

Exception in thread "Timer-1" java.lang.OutOfMemoryError: Java heap space
at org.apache.jackrabbit.core.query.lucene.IndexingQueue.getFinishedDocuments

Increase Java heap size to allocate more memory to JVM:

  1. Stop the server. 
    ./ stop
  2. Open file /apache-tomcat/bin/ (/apache-tomcat/bin/setenv.bat on Windows) in a text editor.
  3. Edit the Xmx parameter to set a new maximum heap size. Default size for Magnolia is 512M, try a higher amount such as 1024M.
  4. Save the file and start the server. 
    ./ start && tail -f ../logs/catalina.out

JAR file does not start

When installing the Enterprise Edition on Windows, you can start the installer by double-clicking the JAR file. If this does not work there is a chance that some application on your system has registered the .jar extension.

You can try to fix it yourself by restoring the association of the .jar extension with the javaw.exe executable. .Right-click the JAR file and select Open With. Typically the javaw.exe file is in C:\Program Files (x86)\java\jre6\bin). Alternatively, start the installer from a command prompt with the following command: java -jar magnolia-enterprise-installer-x.y.z.jar. Make sure the file extension is .jar. Internet Explorer has a tendency to append or change it to .zip.

Activation errors

For issues related to activation keys and the handshaking process, see the Activation errors page.

No indication about conflicting URI mappings in Firefox

In the Pages app, Magnolia informs the editor about a potential URI mapping conflict by placing a warning icon next to the name of the newly created page. Due to a CSS issue Firefox users can't see the icon:

PAGES-145 - Getting issue details... STATUS

#trackbackRdf ($trackbackUtils.getContentIdentifier($page) $page.title $trackbackUtils.getPingUrl($page))
  • No labels