Skip to content

liferay/liferay-portal / workspaces/clarity-solution-workspace/.agents/skills/feature-flags

feature-flags

Verified

Audit, prompt, and enable Liferay feature flags required by a given workflow. Use when a skill needs a flag set (LPD-63311 for MCP, LPD-17564 for CMS and object collaborators on 2026.Q1 and 2026.Q2, etc.), when the user asks to enable a flag, when an API returns 404, or when a Headless endpoint silently returns 400 UnsupportedOperationException.

Feature Flags

Detect the current state of feature flags, report gaps against required sets, and prompt before writing. Many flag gated Headless endpoints fail silently — 400 UnsupportedOperationException with no log output — when the required flag is off. Always check proactively.

When to Invoke

  • A skill declares one or more required flags (the caller passes the list).
  • The user says "check feature flags", "enable LPD-XXXXX", or "what flags do I need for this".
  • An HTTP 404 on a Headless endpoint suggests the flag is off.
  • An HTTP 400 returns UnsupportedOperationException with no useful log output — almost always a flag gated endpoint with the flag disabled.

Workflow

Read Current State

Check both sources, in order:

  1. bundles/portal-ext.properties for feature.flag.LPD-XXXXX=true|false entries.

  2. bundles/osgi/configs/com.liferay.portal.feature.flag*.config for runtime overrides.

A flag missing from both files takes the default declared in rules/feature-flags-catalog.md.

When Tomcat is running and the user is signed in as test@liferay.com, also fetch the UI source of truth at http://localhost:${PORT}/group/control_panel/manage?p_p_id=com_liferay_configuration_admin_web_portlet_InstanceSettingsPortlet&_com_liferay_configuration_admin_web_portlet_InstanceSettingsPortlet_factoryPid=com.liferay.portal.feature.flag.internal.configuration.FeatureFlagsConfiguration for confirmation.

For Docker workspaces, see "Enabling a Flag" below — flag state is read from liferay.env (prebuilt image) or configs/docker/portal-ext.properties (custom image) instead.

Report the Gap

Print a table with: flag, required state, current state, what the flag unlocks, source line. Use rules/feature-flags-catalog.md for the metadata. Group rows by status (OK, NEEDS_ENABLE, NEEDS_DISABLE).

Prompt Before Writing

Never edit portal-ext.properties (or liferay.env) without explicit confirmation. Ask once, list every flag the write will touch, and only proceed on a clear yes. Do not bundle unrelated flags into the same prompt.

Write per Environment

Persist changes per the environment — see "Enabling a Flag" below. Then bounce or restart according to the environment. Follow the restart policy in liferay-rules.md → "Server Restarts". Prefer the live runtime toggle below when it applies, since it needs no restart.

Verify

Reread the state and confirm every required flag is in the desired state. Report success or remaining gaps to the caller skill.

Enabling a Flag

Live, No Restart (Runtime Toggle)

A flag can be flipped on the running portal, with no restart, in Instance Settings → Feature Flags (System Settings for system flags). The change is stored as a portal preference. A switch stays grayed out until every flag listed under its "Dependencies" is on, so turn those on first (on 2026.Q2, LPD-34594 before LPD-17564). On a fresh bundle a Liferay Enterprise Search notice can open over the page and block the switches; close it with Done.

The screen's endpoint, POST /o/com-liferay-feature-flag-web/set-enabled (form params key and enabled), takes session auth only (a browser session or Liferay.Util.fetch), not Basic auth or OAuth. Whether a direct call works depends on the release:

  • 2026.Q3.8: it works both ways (enabled=true and enabled=false, each 200 {"dependentFeatureFlags": []}), and POST /o/com-liferay-feature-flag-web/is-enabled with key answers 200 with the flag's state.
  • 2026.Q2.12: it answers the same 200 and changes nothing, even for LPD-34594, which has no dependency, and is-enabled answers 404. Use the switch.

Either way, verify by effect: reload a page and read Liferay.FeatureFlags['<KEY>']. Still record the flag in portal-ext.properties so a fresh environment matches.

Turning on a flag can start work in the background. On a Hypersonic bundle (2026.Q3.8), enabling LPS-164563 (Data Sets) started a batch engine import, and the portal stopped answering: every request waited on a language resource lock held by a thread blocked on a Hypersonic table lock. A restart ends the hang, and the flag stays on, but it can leave the import unfinished: in one run the import task stayed at STARTED, 7 of the 9 L_DATA_SET_* object definitions stayed inactive, and creating a Data Set answered 400 "Object definition … is inactive". On a new database, set feature.flag.LPS-164563=true in portal-ext.properties before the first start: every L_DATA_SET_* definition then came up active. This was seen on Hypersonic and not tried on another database.

Gotcha: A Stored Toggle Overrides portal-ext.properties

Once a flag has been toggled in the UI or through set-enabled, the stored preference wins over feature.flag.<KEY> in portal-ext.properties (or liferay.env) on every boot. The property is only the default when no preference exists. So a flag someone switched off in the UI stays off after a restart, whatever the properties file says. Fix it with the same toggle.

A new database does this to every Deprecation flag. On the first start of each company, the portal stores every flag of type deprecation as off, so feature.flag.<KEY>=true in portal-ext.properties never applies to one. Turn it on with the toggle. See rules/feature-flags-catalog.md → "Gotcha: A New Database Stores Every Deprecation Flag as Off".

System flags, marked feature.flag.<KEY>.system=true in portal.properties (for example LPD-78863), live on the Deprecation or Developer tab under System Settings → Feature Flags, not Instance Settings. The failure is silent: the gated feature behaves as if off. Verify by effect, not by the properties file.

Tomcat

Add to the source file, then sync to the runtime and restart:

feature.flag.LPD-XXXXX=true
  • Source: configs/local/portal-ext.properties or configs/common/portal-ext.properties (or the active environment from liferay.workspace.environment).
  • Runtime sync: copy the changed file to bundles/portal-ext.properties. The destination is destructive — diff first if bundles/portal-ext.properties may have hand edits.
  • Restart (per liferay-rules.md → "Server Restarts"): stop with bundles/tomcat*/bin/shutdown.sh, wait for the HTTP probe to fail, start with bundles/tomcat*/bin/startup.sh, wait for the HTTP probe to succeed.

Do NOT use blade gw initBundle — it deletes and reinitializes the entire bundle directory.

Docker (Prebuilt Image)

For workspaces using a prebuilt liferay/dxp image, flags are set as environment variables in liferay.env — not in portal-ext.properties. Liferay converts these env vars to portal properties at startup. Add the encoded variable to liferay.env and restart the container (docker compose down && docker compose up).

Docker (Custom Image)

If the compose file uses build:, add the flag to configs/docker/portal-ext.properties or configs/common/portal-ext.properties, then rebuild the image to apply changes.

Env Var Encoding (Docker Prebuilt Image)

Liferay derives the env var name by: (1) prefixing LIFERAY_, (2) uppercasing the whole property name, and (3) replacing each character that is not a letter, digit, or underscore with its CharPool/Unicode endpoint wrapped in underscores. Letters and digits pass through unchanged (the name just must not start with a digit).

Character in property nameEnv var encoding
. (dot)_PERIOD_ (or _46_ Unicode)
- (hyphen)_MINUS_
letters / digitspassed through; letters uppercased — no per character encoding

Worked example — feature.flag.LPD-63311=true becomes:

LIFERAY_FEATURE_PERIOD_FLAG_PERIOD_LPD_MINUS_63311=true

Best practice: rather than hand encoding, look up the exact Env: variable name shown beneath each property in the Liferay Learn Portal Properties reference, and cross check against existing entries in liferay.env if present.

Critical Flags (Quick Reference)

For the full table see rules/feature-flags-catalog.md.

FlagDefaultUnlocks
LPD-63311offMCP server (current path /o/mcp; /o/mcp/sse only on 2025.Q4); on 2026.Q3, only together with the MCPServerConfiguration enabled switch, which is not a flag (see skills/mcp-server/SKILL.md)
LPD-39244offHeadless Admin Fragment / composition API (absent on 2026.Q1, hidden dev on 2026.Q2, beta on 2026.Q3)
LPD-17564offCMS, including the object collaborators API, on 2026.Q1 and 2026.Q2 (needs LPD-34594). The flag is gone from 2026.Q3, where neither needs a flag
LPD-32867offContent provider for dynamic content sets (headless-delivery)
LPD-35443offPage Management API: headless-admin-site site-pages and master-pages (beta on 2026.Q2, release on 2026.Q3)
LPD-74328offPage element / page specification creation and update

Diagnosing an Unknown Flag Gate

If a headless-admin-site (or other Headless) operation returns 400 UnsupportedOperationException and the logs are silent, a missing feature flag is the most likely cause. The Java pattern is:

if (!FeatureFlagManagerUtil.isEnabled(companyId, "LPD-XXXXX")) {
    throw new UnsupportedOperationException();
}

JAX-RS converts the bare UnsupportedOperationException() to a 400 with no useful response body. Ask the user to identify the relevant flag — it is embedded in the *ResourceImpl.class of the implementation jar, but requires decompiling to find. Alternatively, grep the Liferay Portal source on GitHub for LPD- references in the relevant Resource Impl file.

See Also

  • skills/workspace-init/SKILL.md — broader workspace context (Tomcat vs Docker prebuilt vs custom).
  • skills/deploy-and-verify/SKILL.md — destructive copy warning for the portal-ext.properties sync step.

Success Signal

TODO / inferred — verify against a running bundle. The ### Verify step above (reread state; the endpoint that prompted the check no longer returns 404 or 400 UnsupportedOperationException) is the observable completion check; confirm on a live bundle.

References

  • Feature Flags admin doc: https://learn.liferay.com/w/dxp/security-and-administration/administration/configuring-liferay/feature-flags
rea-analysis-optimizationmorluto/reaOptimize REA providers and shared analysis workflows for agent context, latency, CPU, and memory while preserving correctness and Evidence. Use for analysis bottlenecks and cache or query design; CI/test-suite optimization belongs to rea-ci-tests-audit.Stars: 471kUpdated Claude CodeCodexVerifiedInstall
rea-ci-tests-auditmorluto/reaAudit REA CI and test suites for correctness, fixture drift, false passes, and measured performance; use for suite or workflow investigations and efficiency changes, rather than ordinary feature testing or a single test failure.Stars: 471kUpdated Claude CodeCodexVerifiedInstall
rea-tool-designmorluto/reaAudit, investigate, design, or change REA investigation tools, CLI/MCP contracts, provider capabilities, and Evidence semantics.Stars: 471kUpdated Claude CodeCodexVerifiedInstall
ponytail-auditDietrichGebert/ponytailQuality audit of the whole repo: bugs, security, real load, missing tests, speed, and what to delete. Most important first.Stars: 194kUpdated Claude CodeCodexVerifiedInstall