liferay/liferay-portal / workspaces/clarity-solution-workspace/.agents/skills/feature-flags
feature-flags
VerifiedAudit, 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
UnsupportedOperationExceptionwith no useful log output — almost always a flag gated endpoint with the flag disabled.
Workflow
Read Current State
Check both sources, in order:
-
bundles/portal-ext.propertiesforfeature.flag.LPD-XXXXX=true|falseentries. -
bundles/osgi/configs/com.liferay.portal.feature.flag*.configfor 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=trueandenabled=false, each200 {"dependentFeatureFlags": []}), andPOST /o/com-liferay-feature-flag-web/is-enabledwithkeyanswers200with the flag's state. - 2026.Q2.12: it answers the same
200and changes nothing, even forLPD-34594, which has no dependency, andis-enabledanswers404. 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.propertiesorconfigs/common/portal-ext.properties(or the active environment fromliferay.workspace.environment). - Runtime sync: copy the changed file to
bundles/portal-ext.properties. The destination is destructive — diff first ifbundles/portal-ext.propertiesmay have hand edits. - Restart (per
liferay-rules.md→ "Server Restarts"): stop withbundles/tomcat*/bin/shutdown.sh, wait for the HTTP probe to fail, start withbundles/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 name | Env var encoding |
|---|---|
. (dot) | _PERIOD_ (or _46_ Unicode) |
- (hyphen) | _MINUS_ |
| letters / digits | passed 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.
| Flag | Default | Unlocks |
|---|---|---|
LPD-63311 | off | MCP 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-39244 | off | Headless Admin Fragment / composition API (absent on 2026.Q1, hidden dev on 2026.Q2, beta on 2026.Q3) |
LPD-17564 | off | CMS, 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-32867 | off | Content provider for dynamic content sets (headless-delivery) |
LPD-35443 | off | Page Management API: headless-admin-site site-pages and master-pages (beta on 2026.Q2, release on 2026.Q3) |
LPD-74328 | off | Page 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 theportal-ext.propertiessync 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
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| 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: 471k | Updated | Claude CodeCodex | Verified | Install |
| 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: 471k | Updated | Claude CodeCodex | Verified | Install |
| rea-tool-designmorluto/reaAudit, investigate, design, or change REA investigation tools, CLI/MCP contracts, provider capabilities, and Evidence semantics. | Stars: 471k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-auditDietrichGebert/ponytailQuality audit of the whole repo: bugs, security, real load, missing tests, speed, and what to delete. Most important first. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |