Known issues

This page contains information about common issues you may encounter during system installation or use. If you are upgrading to the 6.2 branch, see also Upgrading to Magnolia 6.2.

For additional clarification or help, contact Magnolia support.



Unable to log in with an SSO/OpenID setup

Starting with Magnolia 6.2.10, in your Tomcat configuration, make sure that the CookieProcessor component does not have the sameSiteCookies property set to strict. Instead, set the property to Lax:

<CookieProcessor sameSiteCookies="Lax" />

This supports OpenID top-level redirects while maintaining decent protection against cross-site request forgery (CSRF).

Before Magnolia 6.2.10, Lax was only supported in setups that do not use HTTPS behind a proxy (MAGNOLIA-8112). If that is your case, delete the following line from your Tomcat configuration to make sure that CookieProcessor is not defined:

<CookieProcessor sameSiteCookies="…" />

This approach is less optimal in that there is risk that the effective policy is decided by more recent versions of the browsers themselves, which may lead to unexpected issues.

Server configuration with relaxedQueryChars

Advanced query filters in the Delivery API require extra Tomcat configuration, namely setting relaxedQueryChars="[]|".

HTTP Status 400 - Bad Request
Invalid character found in the request target [/.rest/delivery/tours/v1/magnolia-travels/Vietnam--Tradition-and-Today?mgnl:created[in]=2015-12-01~2015-12-31]. The valid characters are defined in RFC 7230 and RFC 3986
The server cannot or will not process the request due to something that is perceived to be a client error (e.g., malformed request syntax, invalid request message framing, or deceptive request routing).


404 error without trailing slash

When accessing the webapp without the trailing slash (http://localhost:8080/magnoliaAuthor), the user may be presented after login with a 404 page rather than Admincentral. This behavior is configurable via the mapperContextRootRedirectEnabled and mapperDirectoryRedirectEnabled attributes, which can be used to restore the previous behavior.

404 error when reloading page

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 (MGNLUI-2426). Every subsequent reload adds another semicolon.

This issue occurs with earlier versions of the Tomcat application server. To resolve this, upgrade to Tomcat 7.0.47+.

Tomcat 8 using BCEL may throw class format exception

On Tomcat 8.5 or earlier, you may encounter a class format exception.

SEVERE [localhost-startStop-1] org.apache.catalina.startup.ContextConfig.processAnnotationsJar Unable to process Jar entry [module-info.class] from Jar [file:/home/magnolia/dev/magnolia-5.6.6/apache-tomcat-8.5.5/webapps/magnoliaPublic/WEB-INF/lib/javax.json-api-1.1.jar] for annotations
 org.apache.tomcat.util.bcel.classfile.ClassFormatException: Invalid byte tag in constant pool: 19


Apache Commons BCEL is used by Tomcat to scan for annotations. Some Java EE 8 APIs were produced from JDK9 as multi-release JARs. This means they are compatible with Java 8, but may also contain some Java 9 classes including module-info.class. Older Commons BCEL versions do not know how to read such classes.

Tomcat 8.5.12+ updated Commons BCEL to support this. See the extract below from the Tomcat changelog.

60688: Update the internal fork of Apache Commons BCEL to r1782855 to add early access Java 9 support to the annotation scanning code.


Use Tomcat 8.5.12 or later.

IBM WebSphere and Linux

If you experience a JVM crash when running Magnolia 6.2 on IBM WebSphere and Linux, disable the Periscope Result Ranker module by excluding the magnolia-periscope-result-ranker artifact from the dependencies of your project. For example:


JBoss 7.2 with JDK 11

If you are using JBoss 7.2 with JDK 11 to deploy Magnolia, you may get an error during installation. To resolve the issue, add the following lines to WEB-INF/jboss-deployment-structure.xml:

  <module name="jdk.unsupported"/>

MySQL JDBC 8.0.x

If you are using the MySQL JDBC driver 8.0.x to install a new Magnolia instance, you may encounter the following error:

2020-02-14 14:35:07,538 ERROR org.apache.jackrabbit.core.RepositoryImpl: failed to start Repository: org.apache.jackrabbit.core.state.ItemStateException: failed to read bundle (stacktrace on DEBUG log level): deadbeef-face-babe-cafe-babecafebabe: java.sql.SQLSyntaxErrorException: Table '<DATABASE_NAME>.<TABLE_NAME>' doesn't exist

This happens only when you install a new instance from scratch or create database tables during installation. As a workaround, use JDBC 5.1.x or create the tables manually in your database.

Oracle WebLogic

Magnolia 6.2 is not compatible with Oracle WebLogic.

OS X / macOS

Magnolia starts up very slowly

You may encounter this issue after upgrading your macOS to Sierra 10.12 or later.


  1. Open a terminal and figure out the hostname of your Mac. To get the hostname, use the command hostname.


    The command returns the hostname of your Mac. In the given example, the hostname is joesLittleMacBookPro.local.

  2. Open the file /etc/hosts with an editor of your choice. You will edit the file in the next step.

    The file belongs to the system user root. Your user must belong to the group admin; otherwise, you cannot save the changes to the file. You will be asked for your password either when opening the file or when trying to save it.

  3. Add these two lines to /etc/hosts: <hostname>
    ::1 <hostname>

    In place of <hostname>, use your real hostname.

    Most probably, your host file already contains entries starting with and ::1. Just add the real hostname at the end of these lines. Make sure to add a space character before the hostname.

    With the given hostname, the two lines would look like this: localhost joesLittleMacBookPro.local
    ::1 localhost joesLittleMacBookPro.local
  4. Save the file. The system may ask you for your password.

For more information, see:


Cannot publish content with path-based locking

After upgrading to Magnolia 6.2.9, it is not possible to publish content locally. The following errors can be found in the logs:

Log of the Author instance
ERROR info.magnolia.publishing.command.PublicationCommand 08.06.2021 09:42:18 – Receiver: magnoliaPublic8080, error: Unable to contact receiver, HTTP response code: 500.
Log of the Public instance
ERROR info.magnolia.publishing.receiver.operation.jcr.AbstractJcrReceiveOperation 08.06.2021 09:41:52 – UNC path is missing sharename: /\website\/
java.nio.file.InvalidPathException: UNC path is missing sharename: /\website\/

As a temporary workaround, switch the locking mode to compatibility (JCR-based) locking in the configuration of the publishing-core module:


JVM issues

32-bit JVM does not work on Windows

When starting 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, do not use Magnolia CLI to start Magnolia. Instead, start Tomcat directly using <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.


Replace the JVM with a 64-bit version.

Neither JAVA_HOME nor JRE_HOME is defined

You may 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


Set the variables through the Edit the system environment variables dialog.

JRE_HOME is undefined

If you get the following error:

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

You are most probably attempting to run Tomcat with a set JAVA_HOME variable but without a defined JRE_HOME variable.


Set the JRE_HOME variable.

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, select the Private networks checkbox and click Allow access.

Windows firewall

CATALINA_HOME environment variable is not defined

The 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 will not find the Tomcat home directory by simply moving up one level from where you are and will display the following error:

CATALINA_Home not defined

To solve this, define CATALINA_HOME in environment variables. Follow the instructions for the [Neither JAVA_HOME nor JRE_HOME is defined JAVA_HOME environment variable].

JAR file does not start

When installing DX Core 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 file. Right-click the JAR file and select Open with (typically, javaw.exe is in C:\Program Files (x86)\java\jre6\bin). Alternatively, start the installer from a command prompt using java -jar magnolia-dx-core-installer-x.y.z.jar. Make sure the file extension is .jar (Internet Explorer has a tendency to append or change it to .zip).

Other issues

Embedded application server libraries may cause Admincentral to freeze

The Atmosphere Framework bundles several push (Comet) driver implementations. It typically picks the one appropriate for the currently used application server, but if your webapp for some reason brings in other application server libraries (such as Jetty or Grizzly), Atmosphere may pick a wrong driver. This can cause Admincentral to become unresponsive while waiting for push connections.

To mitigate these problems, try to avoid bundling such libraries. See MGNLUI-6899 for more details.

Preview as visitor works only with en as default JVM language

In Magnolia 6.2.11, preview as visitor does not work when English as the default JVM language specifies a variant (for example, en_US as opposed to just en).

For languages other than English, the issue occurs regardless of whether any variants are defined (for example, with both es and es_ES).

For more details and a workaround, see MGNLPN-564.

To fix the issue permanently on your instances, update the Personalization module to version 2.0.10 or later.

Failing POST requests to GraphQL endpoint

When you send a POST request in magnolia-dx-core-demo-webapp 6.2.10 to a GraphQL endpoint, you may get the following 403 Forbidden error:

CSRF token mismatch possibly caused by expired session. Please re-open the page and submit the form again.

For the upcoming fix, see MGNLGQL-101.

In the meantime, you can include the GraphQL module in a webapp based on a 6.2.10 bundle if you add the following configuration to bypass the CSRF security filter:

pattern: /.graphql

REST endpoint not behaving as expected with Java 11

In the Magnolia 6.2.8 webapps (except magnolia-empty-webapp), we have identified an issue filed as BUILD-462.

Generally, the REST endpoints that are affected are those installed or monitored by the magnolia-rest-services and magnolia-rest-integration submodules of the Magnolia REST module. These include:

and any custom endpoint configured as /config/<module-name>/restEndpoints. Whether these endpoints are affected in a specific Magnolia setup depends on how the endpoints are implemented.

The cause of the issue was the update of Tika to 1.26, which pulled in JAXB Runtime 3.0.0.

This issue is resolved in Magnolia 6.2.9 as well as magnolia-dx-core-cloud-webapp-6.2.8-sp1, which is available in the Magnolia Cloud Cockpit.

H2 database

We do not recommend using the H2 database for production environments.

H2 does not accept more than one connection

Our default configuration uses the server mode for H2. If you migrate from Magnolia 5.5.8 or earlier in the 5.5 branch or 5.6.1 or earlier in the 5.6 branch and try to initiate a backup call using CLI or REST, it will fail because H2 does not allow more than one connection at a time. Configure H2 to run in server mode by adding AUTO_SERVER=TRUE to 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 MGNLCE-114.

Index rule warnings when upgrading from 5.4.x directly to 6.2.x

Jackrabbit 2.16 introduced existence checks for node types when refreshing indexing configurations. Previously, it would accept arbitrary node-type names as strings. If your project is not using Magnolia’s SearchIndex implementation, you may find the following warnings in your logs:

2018-07-25 17:48:33,691 WARN rabbit.core.query.lucene.IndexingConfigurationImpl: Unable to refresh index rules
javax.jcr.nodetype.NoSuchNodeTypeException: {}page
    at org.apache.jackrabbit.core.nodetype.NodeTypeRegistry.getNodeTypeDef( ~[jackrabbit-core-2.16.1.jar:2.16.1]
2018-03-16 11:30:57,892 WARN rg.apache.jackrabbit.core.query.lucene.SearchIndex: Exception initializing indexing configuration from: /info/magnolia/jackrabbit/indexing_configuration_website.xml
javax.jcr.nodetype.NoSuchNodeTypeException: {}page
    at org.apache.jackrabbit.core.nodetype.NodeTypeRegistry.getNodeTypeDef( ~[jackrabbit-core-2.16.1.jar:2.16.1]

To mitigate this problem, in your Jackrabbit search configuration files, replace

<SearchIndex class="org.apache.jackrabbit.core.query.lucene.SearchIndex">


<SearchIndex class="info.magnolia.jackrabbit.lucene.SearchIndex">

The warnings should not appear in the logs if you follow our recommendation to upgrade first to the latest release in both your current branch and every intermediate Magnolia branch still maintained before upgrading to the latest release in the Magnolia 6.2 branch. For more details, see How to upgrade.

Too many open files

The embedded Derby database, which can be used instead of the H2 database, 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 another (see Too many open files.

Ubuntu Linux
  1. Find the current maximum number of open files per user in a single session:
    ulimit -n
    The number is 1024 by default, 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 examples. Set the limit according to your 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 will probably also have to add the following line to /etc/systemd/system.conf and /etc/systemd/user.conf: + DefaultLimitNOFILE=65535

  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
    The number is 256 by default, which is too small.

  2. Add ulimit -n 65536 to your ~/.profile file. This increases the limit for the shell.

  3. Create a /etc/sysctl.conf file if it does not exist.

  4. Add the following lines to /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 your system to read the settings from the files you edited.

  6. Type ulimit -n. The response should be 65536 (if not, restart your system).

  7. Install Magnolia

For OS X 10.9 (Mavericks), 10.10 (Yosemite) and 10.11 (El Capitan), see Shell session limit.

For OS X 10.12 (Sierra) and 10.13 (High Sierra), see this thread.

The instructions above apply to Bash shell, not Zsh.

Session de-serialization

When installing or upgrading Magnolia, 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 the signatures of classes that are stored in user sessions, such as permissions and users. The error happens when Tomcat attempts to de-serialize serialized sessions as the container starts. The de-serialization causes the loss of persisted sessions, and users will have to log in again. Otherwise, it is a harmless error and can be ignored.

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 8090 port.

  1. Log into the author instance at http://localhost:8090/magnoliaAuthor/.magnolia.

  2. Go to Configuration.

  3. Set the /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 /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 updated in publishing configuration. Otherwise, publishing changes from the author to the public instance would fail.

  1. On the author instance, go to Configuration > modules > publishing-core > config > receivers.

  2. Under the magnoliaPublic8080 receiver, set the URL property to http://localhost:8090 magnoliaPublic.

  3. Rename the receiver to magnoliaPublic8090. Publish the modified receiver 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.

Java out of memory

If the JVM does not have enough memory, java.lang.OutOfMemoryError may appear in the startup log and Magnolia may fail to start.

Exception in thread "Timer-1" java.lang.OutOfMemoryError: Java heap space
at org.apache.jackrabbit.core.query.lucene.IndexingQueue.getFinishedDocuments
Solution = Increase Java heap size to allocate more memory to the JVM
  1. Stop the server.
    ./ stop

  2. Open the /apache-tomcat/bin/ file (/apache-tomcat/bin/setenv.bat on Windows) in a text editor.

  3. Edit the Xmx parameter to set a new maximum heap size. The default size for Magnolia is 2048M. Try a higher number (for example, 4096M).

  4. Save the file and start the server.
    ./ start && tail -f ../logs/catalina.out

Publishing errors

For issues related to publishing keys and the handshaking process, see the Publishing errors page.

Node locking

We have temporarily added a five-minute timeout for the locking mechanism to mitigate an issue with nodes being locked even after publishing.

For more details about this issue, see EEPUBLISH-28.

New security filter

MAGNOLIA-6865 introduced a new security filter that checks each POST request. As this may affect the functionality of your existing forms, please contact us and we will provide you with more information about this issue.

For security reasons, however, we cannot disclose further details here.

Content stored in CE apps not displayed

In the Community Edition, if you edit content created in an app and the instance has no default i18n support, the content will not be displayed in the detail subapp of the app (MGNLUI-5770).

Rendering single-page applications (SPA)

Currently, the following functionalities are not supported in SPA rendering:

HTTP range requests from Facebook do not work

Facebook uses HTTP range requests to read Open Graph tags. This may cause the Facebook crawler to not work for Magnolia websites. A workaround for this issue is to use a voter that will bypass the gzip filter if the incoming request is of the range type and is coming from Facebook.

  'op': AND
      'headerName': User-Agent
      'pattern': .*facebookexternalhit.*
      'headerName': Range
      'pattern': .*

Virtual URI mappings not working if too many are configured

To mitigate an issue caused by having more than 500 configured virtual URI mappings in light modules, a WARN-level message is now logged when a DirectoryWatcher overflow occurs (MAGNOLIA-7762). We recommend to keep the number of files in a single folder below 100 and to use folder hierarchies whenever possible. For the upcoming fix, see MAGNOLIA-7798.

Natural order not respected in content search results

If you search for content using searchfn.searchPage() or searchfn.searchContent() or by executing search queries directly from a template, the search results will not respect the natural order. This issue is caused by a bug in Apache Jackrabbit reported as JCR-3932.

Until the JCR bug is fixed, do not use searchfn. To get the correct order, execute JCR XPath queries directly.

DL4J/ND4J issues

There are limitations on the deep-learning and search features of the Find Bar, which are provided by the Periscope and Periscope Result Ranker modules.

Off-heap memory starvation

You should configure DL4J memory limits to avoid off-heap memory starvation. This is particularly the case with the -Dorg.bytedeco.javacpp.maxbytes JVM argument. For more details, see MGNLPER-121.

Public webapp cannot be deployed as ROOT along with author instance

When you experience this issue, the following message appears in the logs:

java.lang.NoClassDefFoundError: Could not initialize class org.nd4j.linalg.factory

The issue may occur on more than just one Tomcat instance running on the same VM and the same JDK.

The ND4J library can only be initiated once. Therefore, search result ranking on public instances should be disabled by either changing the configuration of the Periscope Result Ranker module or completely removing the magnolia-periscope-result-ranker module from your WAR package. After this modification, the search function will be available but search results will not be ranked. For more details, see MGNLPER-112.

no jnijavacpp in java.library.path error message

Some environments may throw the following warnings with DL4J 1.0.0-beta7:

no jnijavacpp in java.library.path

For more details, see the reported JavaCV issue.

AVX/AVX2 CPU Support

Advanced Vector Extensions (AVX) are a set of instructions extending the instruction set of the x86 family of microprocessors. AVX was first released in March 2008 for Intel and AMD, and AVX2 was released in 2013. If your hardware uses a processor that does not support AVX2, you will get the following message:

libnd4j binary was built with AVX/AVX2 support, but current CPU doesn't have this instruction set. Exiting now...

By default, Magnolia is shipped with the AVX2 libraries installed:

  • nd4j-native-1.0.0-beta6-macosx-x86_64-avx2.jar

  • nd4j-native-1.0.0-beta6-windows-x86_64-avx2.jar

  • nd4j-native-1.0.0-beta6-linux-x86_64-avx2.jar


If your CPU only supports AVX, use the AVX libraries instead:

  • nd4j-native-1.0.0-beta6-macosx-x86_64.jar

  • nd4j-native-1.0.0-beta6-windows-x86_64.jar

  • nd4j-native-1.0.0-beta6-linux-x86_64.jar


Resizing a GIF image results in an HTTP 500 error

Specific JVMs do not support GIF image compression. In particular, when using version 11 of OpenJDK and its derivatives to process a GIF image via standard image variations, the variations are not rendered and the browser console displays an error:

Failed to load resource: the server responded with a status of 500 () <link>
More details about the error are shown if you open the image link directly:
java.lang.IllegalArgumentException: Unknown compression type!
  • Add a new property called compressionType to the configuration of the output format of your GIF image generator (/modules/imaging/config/generators/<generator-name>/outputFormat) and set its value to LZW.

    Due to a change between Java 8 and Java 11 you have to specifically use upper case LZW.
  • Use a JVM that provides support for processing GIF images (Oracle).

  • Avoid processing GIFs via image variations; use direct links to render the images.

Performance issues

See the Performance issues page.