Liferay Service Builder Compatibility Matrix: Matching Plugin Version to Target Platform

This is LR Tools’ rewrite of a short, practical post by David H Nebinger on Liferay.dev — a build-configuration detail that’s easy to overlook until generated service code stops matching the Liferay version you’re actually targeting.

Why the plugin version matters at all

Run Blade CLI to scaffold a new Liferay Workspace and the generated Gradle plugin versions — including the Service Builder plugin — default to whatever’s newest. For a project targeting the latest Liferay release, that’s exactly what you want.

The problem shows up when your workspace targets an older platform. Service Builder doesn’t just generate generic Java — it generates code against the service APIs and conventions of a specific Liferay release line, and those APIs shift from one quarterly release to the next. The newest Service Builder plugin knows how to generate code for the newest platform, which isn’t the same thing as knowing how to generate correct code for a workspace still targeting, say, 2024.Q1. Point the latest plugin at an older target platform and it can produce service code that doesn’t line up with the APIs actually available there.

The rule that falls out of this: your Service Builder plugin version should match the Liferay DXP version your workspace targets — not just default to whatever’s newest.

The compatibility matrix

Liferay’s Developer Experience team maintains a chart mapping each quarterly release to its corresponding Service Builder plugin version (a version applies to every patch release within that quarterly line):

Liferay Quarterly Version	Service Builder Version
2023.Q3	1.0.463
2023.Q4	1.0.470
2024.Q1	1.0.478
2024.Q2	1.0.485
2024.Q3	1.0.488
2024.Q4	1.0.490
2025.Q1	1.0.496
2025.Q2	1.0.503
2025.Q3	1.0.510
2025.Q4	1.0.513
2026.Q1	1.0.514
2026.Q2	1.0.532

Matching a workspace to a version

Your workspace’s target platform lives in gradle.properties, via the liferay.workspace.product property — something like:

liferay.workspace.product=dxp-2024.q1.10-lts

The quarterly-release portion of that string (2024.Q1 here) is what you look up in the table above:

Workspace Target Platform	Quarterly Release	Service Builder Version
dxp-2024.q1.10-lts	2024.Q1	1.0.478
dxp-2026.q1.8-lts	2026.Q1	1.0.514
dxp-2026.q2.0	2026.Q2	1.0.532

Once you know the right version, pin it in the same file:

com.liferay.portal.tools.service.builder.version=1.0.478

So a workspace targeting 2024.Q1 ends up with both properties set together:

liferay.workspace.product=dxp-2024.q1.10-lts
com.liferay.portal.tools.service.builder.version=1.0.478

Then rebuild as usual:

blade gw buildService
blade gw jar

The trap: stale generated code

Here’s the part that catches people out. The buildService task doesn’t treat a plugin-version bump as a reason to regenerate anything — it only reacts to a change in service.xml or one of the impl classes, and even then only regenerates what that change actually affects. If you’d previously generated service classes with the wrong plugin version, simply pinning the correct version and re-running buildService won’t necessarily fix what’s already there. Clear out the previously generated code first, so Service Builder has to produce every class fresh against the correct version.

Recheck this every time you change target platform

The plugin version and the target platform aren’t independent settings — treat them as one coupled piece of configuration. Move a workspace from:

liferay.workspace.product=dxp-2024.q1.10-lts

to:

liferay.workspace.product=dxp-2026.q2.0

and com.liferay.portal.tools.service.builder.version needs to move to 1.0.532 in the same change. If the generated service code shifts because the plugin version changed, whoever reviews that diff later needs the configuration change sitting right next to it to explain why.

A practical workflow

1. Set or update liferay.workspace.product.
2. Look up the matching quarterly release in the compatibility matrix.
3. Pin com.liferay.portal.tools.service.builder.version to that version.
4. Run buildService, then compile.
5. Commit the generated service code and the workspace configuration change together — not as separate, unexplained commits.

What’s next

Liferay’s Dev Tools team is reportedly working toward making this selection automatic — a future Blade CLI or Workspace plugin release that picks the right Service Builder version based on the configured target platform on its own. Until that ships, this matrix is the practical way to avoid generating service code that’s quietly out of step with the Liferay DXP version you’re actually running.

This article is LR Tools’ rewrite of the original post by David H Nebinger — read it on Liferay.dev for the author’s own framing.