Magnolia 5.3 reached end of life on June 30, 2017. This branch is no longer supported, see End-of-life policy.

Page tree

What has changed since Magnolia 4.5

Magnolia 5.0 is a new major release. The user interface is completely rewritten to be app-centric. It looks and feels different but the basic functionality is all there. Templating works the same way as it did in 4.5. If you already migrated your project to 4.5 then you are well prepared.

The release delivers the following major new features and enhancements:

  • Apps: focused, task-oriented user interfaces for doing one thing at a time
  • Digital asset management (DAM) replaces the DMS and provides image editing
  • Page editor improvements
  • Data module and custom data types are replaced by content apps. Existing data can be run as legacy apps.
  • Vaadin 7 Java Web application framework is used to create the browser user interface. 

  • CKEditor replaces FCKEditor for rich content editing. The new integration is based on custom plugins and allows for the addition of other functionality in a Vaadin-friendly way.
  • Touch interface that works also on tablets.
  • JCR mixin node types replace metadata subnodes.
  • Maven project structure is organized into independent main and UI projects.
  • Old AdminCentral is gradually replaced with apps such as Configuration app and Security app. You can still run old AdminCentral tools as legacy apps.

An aggregated change log for 5.0 contains all the changes.

Updated modules

This release includes the following new module versions:

  • Magnolia 5.0 (CE)
  • Magnolia Activation Module 5.0 (CE)
  • Magnolia Admininterface Legacy Module (4.x compatibility) 5.0 (CE)
  • Magnolia Cache Module 5.0 (CE)
  • Magnolia Categorization Module 2.0 (CE)
  • Magnolia Commenting Module 2.0 (CE)
  • Magnolia DAM Module 1.0 (CE)
  • Magnolia Data Module 2.0 (CE)
  • Magnolia Form Module 2.0 (CE)
  • Magnolia Forum Module 3.0 (CE)
  • Magnolia Groovy Module 2.0.1 (CE)
  • Magnolia Imaging Module 3.0 (CE)
  • Magnolia In-place templating Module 2.0 (CE)
  • Magnolia Mail Module 5.0 (CE)
  • Magnolia Public User Registration 2.0 (CE)
  • Magnolia RSS Aggregator Module 2.0 (CE)
  • Magnolia Resources Module 2.0 (CE)
  • Magnolia Scheduler Module 2.0 (CE)
  • Magnolia Standard Templating Kit 2.5 (CE)
  • Magnolia Templating Samples 5.0 (CE)
  • Magnolia UI 5.0 (CE)
  • contacts-app 1.0 (CE)

The Magnolia team would also like to thank everyone who reported issues, contributed patches, or simply commented on issues for this release. Your continued interest helps us make Magnolia better. Special thanks go to: Chris Daniels, Chris Stephens, Danilo Ghirardelli, Erik Gulliksen, Fabrizio Giustina, Felix Rabe, Frank Sommer, Giancarlo Berner, Jens Denke, Leo Lozes, Maik Jablonski, Markus Jeni, Marvin Kerkhoff, Maximilian Störzer, Michael Aemisegger, Michiel Meeuwissen, Nils Breunese, Ola Montan, Olivier Hermanus, Olivier Marti, Ortwin Glueck, Richard Unger, Samuli Penttilä, Sean McMains, Stefan Baur, Tom Wespi, Tomas Brimor, Umberto Camathias, Vinzenz Wyser, Vivian Steller, and Zam6ak. Translators, thank you for your efforts too!

Is it ready for production?

You can start a new project with the 5.0 release. Bear in mind that not all modules that worked in 4.5 are yet available in 5.0. Try the new release and see if it already has the functionality you require.

The first minor release is 5.1 which will be out at the Magnolia Conference in September. It will close the gap between 4.5 and 5 further.

Missing functionality includes enterprise features such as:

  • Multisite support
  • Approval workflow using inbox notifications. Activation of content works.
  • Diff view for comparing changes between versions
  • Soft locking
  • Forum

How to update from Magnolia 4.5

We recommend that you wait until release 5.2, which is due later in 2013, before updating your project. The 5.2 release will include migration scripts, migration support and migration documentation.

How to migrate from Magnolia 4.4

Updating from 4.4 is a three-step process:

  1. Update your project first to the latest 4.4 series release. At minimum, update to Magnolia 4.4.6, not older.
  2. Migrate your project to 4.5. Understand that migration is not a simple update but an effort that needs to be planned ahead. Follow the procedures described in Migration.
  3. Wait for the 5.2 release later this year. Then update your project to 5.2

Known issues

Java 7 on Mac OS X

Java 7 crashes on Mac OS X. This is not a Magnolia specific issue. Java 7 on OS X is not in our certified stack. We recommend that you use Java 6.

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

JBoss AS 5 class loading issue with Xerces

If you get an exception about SAX parser when deploying Magnolia on JBoss AS 5 you are hitting an issue with Xerces class loading:

org.jboss.xb.binding.JBossXBException: Failed to create a new SAX parser or java.lang.ClassCastException: org.apache.xerces.parsers.XIncludeAwareParserConfiguration

To resolve, remove the Xerces JAR from Magnolia webapps:

  • If you deploy using WAR files, remove the JAR from the archive, for example with the following Unix command: zip -d path-to-magnolia.war WEB-INF/lib/xercesImpl-2.8.1.jar
  • If you deploy using an exploded directory, remove the WEB-INF/lib/xercesImpl-2.8.1.jar file.

See  MAGNOLIA-2577 - Getting issue details... STATUS for details.

JBoss AS 7 class loading issue with Weld

Using JBoss AS 7 together with Weld dependency injection leads to a class loading issue. The symptom is an error message such as: 

Service Module Loader: java.lang.LinkageError: Failed to link org/jbpm/services/task/wih/ExternalTaskEventListener (Module "deployment.magnolia525Author.war:main" from Service Module Loader)
	at org.jboss.modules.ModuleClassLoader.defineClass(
	at [jboss-as-weld-7.1.3.Final.jar:7.1.3.Final]

To resolve this issue, remove the dependency on Weld. Create a JBoss deployment structure XML file with the following content:

<?xml version="1.0"?>
<jboss-deployment-structure xmlns="urn:jboss:deployment-structure:1.2">
            <subsystem name="weld" />

Place the file in /magnoliaAuthor.war/WEB-INF/jboss-deployment-structure.xml.

JBoss AS 7 and log4j

JBoss 7 Application Server adds its own log4j logging configuration. If you want to use your own log4j logging configuration in your deployment, exclude the JBoss configuration first.

Create a new file jboss-deployment-structure.xml under the WEB-INF folder with this content:

  <!-- Exclusions allow you to prevent the server from automatically adding some dependencies -->
      <module name="org.apache.log4j" />
      <module name="org.slf4j" />

See How do I use or log4j.xml instead of using the logging subsystem configuration?

JBoss AS 7 issue loading Vaadin applications

JBoss AS 7 requires that you deploy a gwt-user.jar when deploying a Vaadin application such as Magnolia. Magnolia does not need the JAR at runtime but if you don't supply it JBoss AS 7 will throw an error:

javax.servlet.ServletException: com.vaadin.server.ServiceException: java.lang.NoClassDefFoundError: info/magnolia/ui/vaadin/gwt/client/magnoliashell/shellmessage/ShellMessageWidget : com/google/gwt/user/client/ui/HTML

To resolve this issue, download  gwt-user.jar  and copy it into the Web application's classpath. 

Classpath is a parameter that tells the Java Virtual Machine or the Java compiler where to look for user-defined classes and packages. The classpath of a Magnolia webapp includes any JAR files in /WEB-INF/lib and any classes and resources in /WEB-INF/classes.

Oracle WebLogic 9 conflict with JDOM library

Oracle WebLogic 9 also ships with an old version of JDom which later leads to issues in parsing of XML documents. Issues will be noted as exceptions such as:

java.lang.NoSuchMethodError: org.jdom.Element.getParent()Lorg/jdom/Element;
   at org.jaxen.jdom.DocumentNavigator.getParentAxisIterator(
   at org.jaxen.DefaultNavigator.getParentNode(
   at org.jaxen.expr.NodeComparator.getDepth(
   at java.util.Arrays.mergeSort(

To resolve, provide newer JDOM/Jaxen libraries by adding jdom-1.0.jarjaxen-1.0-FCS-full.jarxom-1.1.jar and saxpath-1.0-FCS.jar to PRE_CLASSPATH variable in the script.

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, 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 rendering of 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:


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

This error can occur on some Linux systems when using the embedded Derby database. Derby opens several file handles and may run over the maximum limit set by the system.

The solution is to increase the limit. The exact procedure varies from one Linux distribution to the next. The procedure below works on Ubuntu. For other systems, see Too many open files.

To set a system wide limit for open files on Ubuntu Linux:

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

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 generate 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 activating changes from the author to public instance fails.

  1. On the author instance, go to Configuration > Activation > Subscribers.
  2. Under the magnoliaPublic8080 subscriber, set the URL property to  http://localhost:8090/magnoliaPublic
  3. Rename the subscriber to magnoliaPublic8090.
  4. Activate the modified 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.

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.

#trackbackRdf ($trackbackUtils.getContentIdentifier($page) $page.title $trackbackUtils.getPingUrl($page))