Issue
When using a Liferay DXP instance deployed on a Jakarta-based image (e.g., Tomcat 10), the liferay-dxp-agent bundle may fail to start. The logs will show an org.osgi.framework.BundleException error related to an unresolved package import.
A key part of the error message will look like this:
Caused by: org.osgi.framework.BundleException: Could not resolve module: liferay-dxp-agent [...]
Unresolved requirement: Import-Package: javax.annotation
Environment
This issue affects Liferay PaaS environments that utilize a Jakarta-based application server, such as Tomcat 10 and newer.
Resolution
The solution is to upgrade the liferaycloud/liferay-dxp service image in your environment to version 5.9.0 or newer.
This updated image contains a fix that resolves the package incompatibility.
Background
The core of the problem lies in the transition from Java EE to Jakarta EE. As part of this evolution, application servers like Tomcat 10 replaced the legacy javax.* packages with the new jakarta.* packages.
The older liferay-dxp-agent expected the javax.annotation package to be available, which is no longer provided in the Jakarta environment, causing the OSGi framework to fail when trying to resolve the agent's dependencies.
To address this, Liferay developed a Jakarta-compatible version of the DXP agent. The updated liferay-dxp service image (v5.9.0+) is intelligent; it detects whether the underlying server is a Jakarta environment and deploys the appropriate version of the agent JAR, ensuring seamless compatibility.