Runtime environment known issues and restrictions

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

For Distributed operating systems

See also Developer Tools known restrictions.

List of known issues and restrictions:

Minimum supported Java levels

Liberty is supported by any compliant Java™ SE 8, 11, 17, or 21 runtime environment (JRE) or Java SDK, subject to the minimum supported levels shown for the following specific implementations.

Important:

Java SE 17 is the recommended Java SDK because it provides the latest features and security updates. As an alternative to installing Java SE 17, you can install another supported Java SDK version. Liberty runs on any of the Java SE versions that are listed in the Java SE versions column of the Supported Java Releases table on the Open Liberty website.

  • The Liberty end of support date for Java SE 8 is October 2026, fix pack 26.0.0.10.
  • The Liberty end of support date for Java SE 11 is October 2026, fix pack 26.0.0.10.
  • The Liberty end of support date for Java SE 17 is October 2027, fix pack 27.0.0.10.
  • The Liberty end of support date for Java SE 21 is October 2029, fix pack 29.0.0.10.

For more information, see Removal notices.

For IBM i platformsImportant: The IBM i platform supports only Java SE 8, Java SE 11, and Java SE 17. Java SE 21 is not yet supported on IBM i.
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.
For IBM i platforms
  • For IBM i V7R4, the minimum JDK level is IBM Java SE 8.0 32-bit JVM (5770JV1 option 16) or IBM Java SE 8.0 64-bit JVM (5770JV1 option 17).
  • [22.0.0.3 and later]For IBM i V7R5, the minimum JDK level is IBM Java SE 8.0 32-bit JVM (5770JV1 option 16) or IBM Java SE 8.0 64-bit JVM (5770JV1 option 17).

For Distributed operating systemsOn distributed platforms, 32-bit or 64-bit Java is supported.

For Distributed operating systemsFor 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.

Java SE 11 runtime environment
Running on Java SE 11 with IBM Semeru Runtimes for Java™ 11 is supported. The minimum supported level is Java version 11.0.2. Note that significant changes in the Java SE platform occurred between Java SE 8 and Java SE 11, so zero-migration is not guaranteed.
Java SE 17 runtime environment
As of Liberty 21.0.0.10, running on Java SE 17 is supported.
[23.0.0.10 and later]Java SE 21 runtime environment
As of Liberty 23.0.0.10, running on Java SE 21 is supported.

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.

Fileset restrictions

The following restriction applies to Filesets:
  • 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"/>

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.

Notes:
  • 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.

If you are using generic JCA support, the following restrictions apply:
  • 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.

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.

Shared session applications restrictions

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. In addition, shared session applications that use the IBMApplicationSession interface are not supported in Liberty.

Liberty applications that run in IBM Cloud Private

When you deploy Liberty applications in IBM Cloud® Private, the following restrictions exist:
  • 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.

appSecurity-2.0 feature restrictions

For the appSecurity feature, the following restrictions apply:
  • 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

For the beanvalidation-1.0 feature, the following restriction applies:
  • There is no support for bean validation inside OSGi applications.
For the beanValidation-1.1 feature, the following restrictions apply:
  • 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

CDI feature restrictions

For the cdi-1.2 feature, the following restriction applies:
  • For JNDI lookups inside a method that is annotated @Observes @Initialized(ApplicationScoped.class), only the java:app namespace is available during the method invocation. For Liberty 18.0.0.1 and earlier, if you need another namespace, move the class into a WAR file.

    To fix the problem, upgrade to Liberty 18.0.0.2. Without the fix, no namespaces are available unless you move the class into a WAR file.

For the cdi-2.0 feature, the following restriction applies:
  • The cdi-2.0 feature requires a minimum IBM Java level of 8.0.5.6. This Java version contains a fix that prevents an IllegalAccessException from occurring against a Weld interface called ObserverExceptionHandler.

collectiveController-1.0 feature restriction

If you start a collective controller server and then change your IP configuration, the controller no longer functions correctly.

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

The following dynamic cache features are not available or have limited availability:
  • 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

The following restrictions apply to EJB features:
  • 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.

j2eeManagement-1.1 feature restriction

For the j2eeManagement-1.1 feature, the following restriction applies:

  • The Management EJB getListenerRegistry() method is not supported. You cannot register an event notification listener in a Management EJB component.

jacc-1.5 feature restrictions

For the jacc-1.5 feature, the following configurations are ignored:
  • 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.

jaxb-2.2 feature restrictions

For the jaxb-2.2 feature, the following restrictions apply:
  • If your application requires JAXB API classes and has already been started, and the jaxb-2.2 server feature is to be enabled, you must restart the server with the --clean option so that you application can call the JAXB 2.2 API and implementation classes that are provided by the jaxb-2.2 feature. Otherwise, your application might still bind to the JAXB API and implementation classes that are provided in the Java SDK
  • If the jaxb-2.2 server feature is enabled, and you want to use your own JAXB API and implementation classes in your application, you must place your own JAXB API and implementation JAR files into the /WEB-INF/lib directory of your application, and configure the class loader of your application to use parentLast delegation behavior. Otherwise, the JAXB API and implementation classes that are provided by the jaxb-2.2 feature always take effect. For more information of configuring class loader behavior for you applications on Liberty, see Overriding a provided API with an alternative version.

jaxws-2.2 feature restrictions

For the jaxws-2.2 feature, the following restrictions apply:
  • Because the jaxws-2.2 feature depends on the jaxb-2.2 feature, the jaxb-2.2 feature restrictions also apply to the jaxws-2.2 feature.
  • If your application requires JAX-WS API classes and has already been started, and the jaxws-2.2 server feature is to be enabled, you must restart the server with the --clean option so that you application can call the JAX-WS 2.2 API and implementation classes that are provided by the jaxws-2.2 feature. Otherwise, your application might still bind to the JAX-WS API and implementation classes that are provided in the Java SDK
  • The web services binding file for Liberty is the ibm-ws-bnd.xml file. The following web services binding files for WebSphere Application Server traditional are not supported:
    • ibm-webservices-ext.xmi
    • ibm-webservices-bnd.xmi
    • ibm-webservicesclient-ext.xmi
    • ibm-webservicesclient-bnd.xmi
    • ws-security.xml
  • The Apache Axis2 configurations or classes are not supported.
  • The web service providers that implement javax.xml.ws.Provider<OMElement> or javax.xml.ws.Provider<String> interface are not supported.
  • The content-id attribute of MIME attachments must be enclosed with angle brackets for Liberty. For example, <testID>.
  • The -inlineSchemas option is not supported by the wsgen tool that is provided by Liberty.
  • Enable MTOM if you want to transfer big binary data using JAX-WS web services to avoid the Out of Memory (OOM) error.
  • For web service applications, if the service client and service provider are not in the same application and the WSDL file in the service provider application is changed, you need to restart the web service client application manually to avoid the WSDL definition cache issue.

jpa-2.1 feature restrictions

For the jpa-2.1 feature, the following restrictions apply:
  • If you must use an alternate JPA 2.1 persistence provider, use the jpaContainer-2.1 feature instead.
  • Features and annotations that are specific to EclipseLink are exposed as third-party API packages. To enable these, you must configure your classloader for third-party classloading.

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:
    1. 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.
    2. 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

For the monitor-1.0 feature, the following restriction applies:
  • When the feature is removed from the server.xml file, you must restart the server to make the JAX-WS applications work.

openapi-3.0 feature restrictions

For the openapi-3.0 feature, the following restrictions apply:

  • 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

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.
You can use the restConnector-2.0 feature instead.

scim-1.0 feature restrictions

The following restrictions apply for the scim-1.0 feature:
  • 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

For the sipServlet-1.1 feature, the following restrictions apply to Session Initiation Protocol (SIP) support:
  • 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 feature, the following restriction applies:
  • 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.

ssl-1.0 and transportSecurity-1.0 feature restrictions

For the ssl-1.0 and transportSecurity-1.0 features, the following restrictions apply:

  • Java SE 11 introduced a new TLS protocol version, TLSv1.3. This new protocol version is not backwards compatible with existing Liberty features and therefore is globally disabled until Java SE and/or Liberty code changes are made to accommodate the usage of TLSv1.3. The TLSv1.3 protocol is also included if you use IBM Semeru Runtimes for Java™ 11 or later. For more information about using OpenSSL for cryptographic acceleration with IBM Semeru Runtimes for Java™ 11, see the Semeru Runtimes security migration guide
  • When the ssl-1.0 feature is enabled, you acquire the Liberty default SSLContext class by using the SSLContext.getDefault() method. However, when transportSecurity-1.0 is enabled, the SSLContext.getDefault() method returns the Java Secure Socket Extension (JSSE) SSLContext class. Therefore, changing from one feature to the other might require you to update your application code. To obtain the default Liberty SSLContext class when the transportSecurity-1.0 feature is enabled, use the JSSEHelper.getInstance().getSSLContext(null, null, null) method instead of the SSLContext.getDefault() method.

wmqJmsClient-1.1 feature restrictions

For the wmqJmsClient-1.1 feature, the following restrictions apply:
  • 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

For the wmqJmsClient-2.0 feature, the following restrictions apply:
  • 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.