Runtime environment known issues and restrictions
There are some known restrictions that apply when you work with Liberty runtime environment.

See also Developer Tools known restrictions.
Release notes
If the operating system has no release notes, when you click the link, the resulting page indicates that no release notes were found.
List of known issues and restrictions:
- General restrictions:
- Minimum supported Java levels
- The installation directory name and path cannot include non-ASCII characters
- Changing the JDBC data source at run time might result in JPA failures
- An application that relies on a result being returned by getRealPath must be deployed as an expanded application, not as a WAR file
- WebSphere Application Server traditional scripts do not work with Liberty
- Fileset restrictions
When you unpublish a shared library, it cannot be deleted until the server is stopped
- java:global lookups restrictions
- Applications not starting in an embedded Liberty server
- WebSphere MQ resource adapter and generic JCA support related restrictions
- Versioning is not possible for applications in the dropins directory
- Collective, dynamic routing, and scaling features cannot be used with the cdi-1.2 feature
- Shared session applications must store session objects in shared libraries
- Configuring session persistence
- Ported locally transacted JMS sessions do not work in Liberty
- Liberty's use of IBM MQ messaging
Liberty applications that run in IBM Cloud Private
Restrictions for JSON Logging
- Restrictions that are specific to Liberty features:
- Admin Center feature restrictions
- appClient-1.0 feature restriction
- appSecurity-2.0 feature restrictions
- Bean validation feature restrictions
- concurrent-1.0 feature restrictions
- Dynamic cache feature restrictions
- Enterprise JavaBeans (EJB) feature restrictions
- jacc-1.5 feature restrictions
- jpa-2.1 feature restrictions
- jsf-2.2 feature restrictions
- jsp-2.2 feature restrictions
- logstashCollector-1.0 feature restrictions
- monitor-1.0 feature restriction
openapi-3.0 feature restrictions
- requestTiming-1.0 feature restrictions
- restConnector-1.0 feature restriction
- scim-1.0 feature restrictions
- socialLogin-1.0 feature restrictions
- sipServlet-1.1 feature restrictions
- wmqJmsClient-1.1 feature restrictions
- wmqJmsClient-2.0 feature restrictions
- Modifying the dataSource, jdbcDriver, connectionManager, and JDBC vendor properties at run time might result in JPA failures
Minimum supported Java levels
![[17.0.0.3 and later]](../ng_v17003plus.gif)
- Java SE 6 runtime environment
Important: Support for using Java SE 6 with WebSphere Liberty ended in September 2017. The Liberty kernel was recompiled for 17.0.0.3. Beginning with 17.0.0.3, the Liberty kernel no longer runs with Java SE 6. If you continue to use Java SE 6 on earlier releases after the end of support date, you might expose your environment to security risks.
Java SE 8 is the recommended Java SDK because it provides the latest features and security updates. As an alternative to installing Java SE 8, you can install another supported Java SDK version.
- Java SE 7 runtime environment
- For the Java SDK from IBM, the minimum supported level is IBM Runtime Environment, Java Technology Edition 7.0.4.1. For the JDK from Oracle on Windows and Linux, the minimum supported level is Java SDK/JRE/JDK 7.0.17. For the JDK from Oracle on Mac OS X, the minimum supported level is Java SDK/JRE/JDK 7.0 Update 15.
- Important: Beginning in fix pack 19.0.0.3, the Liberty kernel no longer runs with Java SE 7. For more information, see Removal notices.
- Java SE 8 runtime environment
- For the Java SDK from IBM, the minimum supported level is IBM SDK, Java Technology Edition, Version 8. For the JDK from Oracle, the minimum supported level is Java 8 update 25.
On distributed platforms, 32-bit or 64-bit Java is supported.
For Windows and Linux systems, you can use either the JDK from Oracle or the Java SDK from IBM. If you
are developing applications on Windows or Linux, and you plan to deploy those applications to a server that is running
on WebSphere Application Server traditional, use the Java SDK from IBM. For HP
systems and Mac OS, use the JDK from Oracle.
For IBM i V7R1, the minimum JDK level is IBM
Java SE 7.0 32-bit JVM (5761JV1 option 14) or IBM
Java SE 7.0 64-bit JVM (5761JV1 option 15). For IBM i V7R2 and V7R3, the minimum JDK level is IBM
Java SE 7.0 32-bit JVM (5770JV1 option 14) or IBM
Java SE 7.0 64-bit JVM (5770JV1 option 15).
The installation directory name and path cannot include non-ASCII characters
Recent JVMs do not fully support use of non-ASCII characters with the -jar and -javaagent commands. Use only ASCII characters in your installation directory names and paths.
Changing the JDBC data source at run time might result in JPA failures
If the database dictionary type is not specified through properties, it is detected and calculated by OpenJPA when the first entity manager is created and the database connection is made. This database dictionary type is used for all entity managers that are subsequently created. If the JDBC data source is changed while an application is running, the entity manager factory does not detect this change and continues to use the old dictionary for operations against the new data source. This can result in failures if the database is changed to a different vendor.
When you change a database to a different vendor, restart the application.
Modifying the dataSource, jdbcDriver, connectionManager, and JDBC vendor properties at run time might result in JPA failures
If you update the configuration of dataSource, jdbcDriver, connectionManager or any of the JDBC vendor properties lists (for example, properties.db2.jcc or properties.oracle) while the server is running, you might see J2CA8040E failures. These failures state that multiple dataSource elements cannot be associated with a single connectionManager. These failures are generated even if your configuration associates only one connectionManager with the dataSource element.
When you make updates to the configuration of any of these JDBC resources, restart the server.
An application that relies on a result being returned by getRealPath must be deployed as an expanded application, not as a WAR file
The Java EE specification states that the getRealPath() method returns a null value if the content is being made available from a web archive (WAR) file. When you deploy a WAR file to Liberty, it does not automatically extract the archive file into a directory structure. Therefore, the application might fail to start. If your application relies on a result being returned by getRealPath(), you must deploy the application as an expanded web application, not as a WAR file. For example, you can manually extract the WAR file and copy the expanded application to the dropins directory.
WebSphere Application Server traditional scripts do not work with Liberty
You cannot use any of the scripts under the bin directory of the WebSphere Application Server traditional to administer Liberty.
Fileset restrictions
- Filesets do not recursively explore subdirectories of the
base directory. For example, the following instructions are not supported:
<fileset id="testFileset" dir="\temp" includes="**\a.jar"/> <fileset id="testFileset" dir="\temp" includes="a\a.jar"/> <fileset id="testFileset" dir="\temp" includes="*\a.jar"/> <fileset id="testFileset" dir="\temp" includes="a\b\a.jar"/>

When you unpublish a shared library, it cannot be deleted until the server is stopped
When you unpublish a shared library from a server, the library JAR file is not immediately released from the server. Therefore, the operating system does not know that the file is no longer in use, and does not allow the file to be deleted. When you next stop the server, the library JAR file is released and you can delete the file.
java:global lookups restrictions
Resources defined in applications with java:global lookups can be used to access names declared by applications that are deployed only in the current server.
Applications not starting in an embedded Liberty server
Ensure that the Java process that starts the embedded Liberty server was started with the -javaagent JVM argument that pointed to the libertyInstallDir/bin/tools/ws-javaagent.jar. If the -javaagent JVM argument is not used the server runtime starts, but applications fail to start with no obvious exceptions.
WebSphere MQ resource adapter and generic JCA support related restrictions
The WebSphere® MQ resource adapter can be used within the WebSphere Application Server Liberty by using either the wmqJmsClient-1.1 or wmqJmsClient-2.0 feature or by using generic JCA support.
You can use the WebSphere MQ resource adapter version 7.5 with Liberty version 8.5.5 and later. If you want to use WebSphere MQ resource adapter version 8.0, which is based on JMS 2.0 resource adapter, you must ensure that you are using the latest Liberty version that is compatible with the JMS 2.0 resource adapter.
- With Liberty version 8.5.5.2, the wmqJmsClient-1.1 feature must be used with a IBM MQ resource adapter version 7.5.0.5 or later.
- With Liberty version 8.5.5.6, the wmqJmsClient-2.0 feature must be used with a IBM MQ resource adapter version 8.0.0.3 or later.
To know more about the version compatibility information between WebSphere MQ resource adapter and Liberty, see the Reference to obtain the WebSphere MQ resource adapter.
- To run the IBM® WebSphere MQ resource adapter on z/OS®, you must use the wmqJmsClient-1.1 or wmqJmsClient-2.0 feature.
- Tracing and logging are not integrated within the Liberty trace system by using generic JCA. Trace is written to a separate file, and it must be enabled by setting the system properties. The procedure to enable tracing is the same as configuring the WebSphere MQ classes for JMS trace facility for a Java Standard Environment. See Java Standard Environment Trace stanza.
- The IBM MQ classes for Java are not supported in Liberty. They must not be used with either the IBM MQ Liberty messaging feature or with the generic JCA support. For more information, see Using WebSphere MQ Java Interfaces in J2EE/JEE Environments.
Versioning is not possible for applications in the dropins directory
For applications in the dropins directory, the file name and file extension are used by the application monitor to determine the type of application, and to generate the application id and application name. Therefore, it is not possible to specify the version number for the application by using the file name or file extension. In a production environment, you are not recommended to use the dropins directory.
Collective, dynamic routing, and scaling features cannot be used with the cdi-1.2 feature
Do not use the collectiveController-1.0, collectiveMember-1.0, clusterMember-1.0, dynamicRouting-1.0, scalingController-1.0, or scalingMember-1.0 feature with the Contexts and Dependency Injection 1.2 (cdi-1.2) feature.
Shared session applications must store session objects in shared libraries
When you are using the shared-session-context application extension, or <shared-session-context value="true"/> in ibm-application-ext.xml, all objects that are stored in the session must be available in the shared libraries that are associated with the application so that the session can be invalidated.
Configuring session persistence
There is only one server.xml file for each server, not a server.xml file for each EAR or WAR file. You set session persistence in a database by adding:
<httpSessionDatabase id="SessionDB" dataSourceRef="SessionDS" ... />
In Liberty, this setting for the database applies to all EAR and WAR files. It is not possible to set up some databases with session persistence and others without.
Ported locally transacted JMS sessions do not work in Liberty
In WebSphere Application Server traditional, you can develop applications to take advantage of locally transacted JMS sessions. When you port these applications to Liberty, these applications behave differently or do not work at all.
Even though WebSphere Application Server traditional allows locally transacted JMS sessions, porting a WebSphere Application Server traditional locally transacted JMS session to Liberty is not allowed.
Liberty's use of IBM MQ messaging
When Liberty is using IBM MQ as a messaging provider, the reuse criteria of a free connection of the JMS connection pool is different from the reuse criteria in WebSphere Application Server traditional. Specifically, the reuse rate of Liberty is much lower than the reuse rate of WebSphere Application Server traditional if a JMS application uses container authentication for a connection factory and several authenticated users use the same connection pool. The Liberty reuse rate is lower because the free connection that is created by an authenticated user cannot be reused by other authenticated users in the Liberty and can result in frequent connection regeneration. You can use application authentication with username and password properties of properties.wmqJms if the reuse rate of Liberty does not satisfy performance requirements.
![[17.0.0.3 and later]](../ng_v17003plus.gif)
Liberty applications that run in IBM Cloud Private
- Auto scaling is based on CPU usage only, not custom metrics.
- Ingress supports basic configuration and annotations, such as a single context root, only.
- You might experience a problem accessing applications that use Ingress on the HTTP protocol. If you access an application on http://proxy_host/, then you are redirected to port 80, which is not correct, and the application cannot be accessed. Remove port 80 from the URL to fix the issue.
- Currently, the Liberty Helm chart only supports persistence of transaction logs for a single replica.
![[18.0.0.1 and later]](../ng_v18001plus.gif)
Restrictions for JSON Logging
- When binary logging is configured, log records that are written to the console remain in basic format even when JSON logging is enabled.
- When JSON logging is enabled on z/OS, some messages might be missing at the server startup period.
- When JSON logging is enabled, throwables that are logged to the System.out/err are not truncated with [internal classes].
Admin Center feature restrictions
![[16.0.0.4 and later]](../ng_v16004plus.gif)
- Job logs from remote machines cannot be viewed unless each remote server that has batch jobs or job logs has a CORS configuration. See Viewing Java batch jobs in Admin Center.
- If instance logs are viewed, expect an error if the executions are spread across multiple hosts.
- The Java Batch tool requires you to use a persisted database with the batchManagement-1.0 feature.
appClient-1.0 feature restriction
- The feature does not support Java EE application clients and can launch only stand-alone client programs.
appSecurity-2.0 feature restrictions
- For EJB applications, the run-as-mode of SYSTEM_IDENTITY is not supported in the extension settings of the ibm-ejb-jar-ext.xml file.
- The getCallerIdentity API is not supported for Singleton session beans.
- Role names can be referenced by the HttpServletRequest.isUserInRole and EJBContext.isCallerInRole APIs or by elements in the deployment descriptor without first declaring the role names using the @DeclareRoles annotation or the <security-role/> element in the deployment descriptor. However, roles must be declared before being used in WebSphere Application Server traditional.
Bean validation feature restrictions
- There is no support for bean validation inside OSGi applications.
- There is no support for bean validation inside OSGi applications.
- Applications that provide a custom ConstraintValidatorFactory implementation in a validation.xml file with the beanValidation-1.0 feature do not compile against the Bean Validation 1.1 API.
- If a validation.xml file is not located in the module it is associated
with, then there can be only one validation.xml file and the
com.ibm.ws.beanvalidation.allowMultipleConfigsPerApp property must be set to
false in either of the following files:
- jvm.options
-Dcom.ibm.ws.beanvalidation.allowMultipleConfigsPerApp=false
- bootstrap.properties
com.ibm.ws.beanvalidation.allowMultipleConfigsPerApp=false
- jvm.options
concurrent-1.0 feature restrictions
For the concurrent-1.0 feature, the following restrictions apply:
For the thread context of type securityContext, any custom information in the subject that was not added by using a JAAS login module is not propagated. For example, if the submitter's subject contains a custom Principal that was added by a TAI, the propagated subject does not contain this custom Principal.
Dynamic cache feature restrictions
- Cache replication is not supported.
- Only the high performance disk caching mode is supported by random and size-based eviction techniques.
- There is no support for Web Services client and server-side caching as well as portlet cache in the cachespec.xml file.
- There is no support for servlet caching of SingleThreadModel servlets.
- Defining cache configuration by using properties files is not supported for JAR files that contain only Enterprise JavaBeans (EJBs).
- Limiting a heap cache size works only for 32-bit Java virtual machines (JVM).
Enterprise JavaBeans (EJB) feature restrictions
- EJB modules before version 3.0 are not supported when you use the EJB Lite features only because EJB homes are not included in EJB Lite. This restriction also means that bindings and extensions that use the .xmi file format rather than the .xml file format are not supported.
- Session beans are not bound to the ejblocal namespace, which means JNDI lookups and ejb-ref binding names must use java:global, java:app, or java:module names. The simple-binding-name and interface binding-name elements are ignored in ibm-ejb-jar-bnd.xml files.
- The stateful bean passivation directory is not configurable. Files are passivated to the server work area.
jacc-1.5 feature restrictions
- Authorization information (the users and groups attributes of the authorizations attribute) in an ibm-application-bnd.xml file or an ibm-application-bnd.xmi file of the application's ear file.
- Authorization information (the user, group, and special-subject attributes of the security-role attribute in the application-bnd element) in the server.xml file.
jsf-2.2 feature restrictions
- When you use the jsf-2.2 feature with a faces-config.xml file and specify version 2.2 and namespace, you get an error.
- There are feature conflicts if you enable jsf-2.2 with cdi-1.2, ejb-3.2, and jpa-2.1.
jsp-2.2 feature restrictions
- There is no support for the useInMemory configuration option to only store the translated JSP file in memory.
jpa-2.1 feature restrictions
- You cannot use an alternate JPA 2.1 provider. If you need 2.1 support, you must use the built in provider.
- You cannot use any EclipseLink-specific features or annotations in your application. You can only use the javax.persistence APIs.
logstashCollector-1.0 feature restrictions
The following limitations apply to the logstashCollector-1.0 feature:- Data Loss – Some events that are generated in Liberty might not be forwarded to Logstash as
expected. Data loss might occur under the following scenarios:
- Starting the Liberty server before the Logstash server is started. It is recommended that you start the Logstash server before you start the Liberty server.
- Heavy load conditions. Events might be dropped in cases where events are created in Liberty faster than they can be processed by the Liberty event pipeline, Logstash, and any other downstream consumers. Liberty uses buffers to avoid data loss when event creation is briefly faster than event consumption.
- The logstashCollector-1.0 feature is tested and is compatible with Logstash V2.x and Logstash V5.x.
monitor-1.0 feature restriction
- When the feature is removed from the server.xml file, you must restart the server to make the JAX-WS applications work.
![[17.0.0.3 and later]](../ng_v17003plus.gif)
openapi-3.0 feature restrictions
For the openapi-3.0 feature, the following restrictions apply:
- Unlike apiDiscovery-1.0, openapi-3.0 does not currently support the Try it out! feature.
- When you view your documentation at either http://Liberty_host:http_port/api/docs, https://Liberty_host:https_port/api/docs, or https://Liberty_host:https_port/ibm/api/docs with Microsoft Internet Explorer 11, it returns a YAML document that is not properly formatted. As a workaround, use a browser such as Mozilla Firefox or Google Chrome browser.
- openapi-3.0 does not support OASProvider configurations for multiple languages. Specify providers that return only one result.
- Not all the JAX-RS and OpenAPI annotations are supported currently.
- If the value of the validation attribute is changed while the server is running, previously loaded applications will need to be restarted in order for the new validation setting to take effect for those applications.
- The following portions of the OpenAPI document are not validated:
- component
- discriminator
- encoding
- extension
- header
- link
- schema
- scopes
- xml
requestTiming-1.0 feature restrictions
- The requestTiming-1.0 feature, when activated, has been shown to have a 4% adverse effect on the maximum possible application throughput when measured with the DayTrader application. While the effect on your application might be more or less than that, you should be aware that some performance degradation might be noticeable.
restConnector-1.0 feature restriction
For the restConnector-1.0 feature, the following restriction applies:
- Users of the restConnector-1.0 feature or any feature that includes restConnector-1.0, such as collectiveMember-1.0 and collectiveController-1.0, who want to run applications that contain a custom JAXRS 2.0 runtime must add the jaxrs-2.0 feature to that server.
scim-1.0 feature restrictions
- The members attributes are not retrieved while you search for groups.
- The groups attributes of users are not retrieved while you search for users.
- The Canonical type of direct/indirect cannot be set for groups attribute of users.
- Only one email attribute of user of Canonical type, work, can be defined.
- Only one ims attribute of user of Canonical type, work, can be defined.
- Extended schema attributes of SCIM such as entitlements, roles, and x509Certificates cannot be set or returned.
- The userName attribute cannot be used with some other attributes in a filter.
- For users in Basic and SAF registries, only userName, displayName, id, schema, meta.location, and groups can be set. The userName and displayName have the same value.
- List/query with Basic and SAF registries does not work the same as the ldapRegistry registry.
- Operators like pr, gt, ge, lt, le, and, or, and () does not work with Basic and SAF registries. Also, only one operator must be used in the filter for Basic and SAF registries.
- Basic and SAF are read only registries.
- While you create user, the groups attribute cannot be set.
sipServlet-1.1 feature restrictions
- SIP counters for Performance Monitoring Infrastructure (PMI) are not supported.
- SIP digest authentication and JSR 289 Section 17, the security section, are not supported.
- Clustering and SIP dialog persistence are not supported.
socialLogin-1.0 feature restrictions
- For the socialLogin-1.0, the default social media selection form may not work properly in Internet Explorer on the Windows Server 2012 operating system. When you choose a provider and the form is submitted, Internet Explorer might submit the displayed button text as the default value instead of the HTML value configured for the button. To get around this restriction, you might use a different web browser. Browsers other than Internet Explorer function correctly with the default selection form.
wmqJmsClient-1.1 feature restrictions
- You must manually set the PATH variable in the Windows environment variables to point to the IBM MQ installation bin directory. You must set this path variable when the application uses the BINDING connection mode.
- The IBM MQ classes for Java are not supported in Liberty. They must not be used with either the IBM MQ Liberty messaging feature or with the generic JCA support. For more information, see Using WebSphere MQ Java Interfaces in J2EE/JEE Environments.
- The BINDINGS_THEN_CLIENT transport type of IBM MQ resource adapter is not supported for the wmqJmsClient-1.1 feature.
- The Advanced Messaging Security (AMS) feature is not included for the wmqJmsClient-1.1 feature.
wmqJmsClient-2.0 feature restrictions
- You must manually set the PATH variable in the Windows environment variables to point to the IBM MQ installation bin directory. You must set this path variable when the application uses the BINDING connection mode.
- The IBM MQ classes for Java are not supported in Liberty. They must not be used with either the IBM MQ Liberty messaging feature or with the generic JCA support. For more information, see Using WebSphere MQ Java Interfaces in J2EE/JEE Environments.
- The BINDINGS_THEN_CLIENT transport type of IBM MQ resource adapter is not supported for the wmqJmsClient-2.0 feature.