Author mode error handling differences in AEM Sites environments
In lower environments, component-level failures are shown inline, allowing the rest of the page to render. In higher environments, similar errors cause the entire page to fail to render.
Description description
In Adobe Experience Manager Sites, the same page displays different error handling behaviors in author mode depending on the environment. In lower environments, component-level failures are shown inline, allowing the rest of the page to render. In higher environments, similar errors cause the entire page to fail to render or become un-authorable, even though the codebase is identical across environments.
Environment
Adobe Experience Manager as a Cloud Service (all versions)
Symptoms
- In lower environments, component errors are displayed inline and the page continues to load.
- In higher environments, the same errors cause the page to fail completely in author mode.
- The root cause is often a missing component class reference, which throws an exception in every environment, but the resulting user experience differs.
Cause
This difference is due to the default configuration of the WCMDeveloperModeFilter. This filter is enabled in lower environments and disabled in higher environments. When enabled, it catches component exceptions and allows the page to render with inline error messages. When disabled, component exceptions cause the entire page to fail.
Resolution resolution
Follow these steps to resolve the issue.
- Understand the
WCMDeveloperModeFilterbehavior: In lower environments,WCMDeveloperModeFilteris enabled by default. It catches component exceptions and displays inline error messages, allowing the rest of the page to render. In higher environments, the filter is disabled by default, so component exceptions cause the entire page to fail. - Do not disable Developer Mode in lower environments: Adobe recommends keeping Developer Mode enabled in lower environments to help identify and fix component errors before code is promoted to higher environments. Disabling Developer Mode in lower environments can hide component-level failures, making it harder to detect issues early.
- Check Developer Mode status: Review the configuration for
com.day.cq.wcm.core.impl.WCMDeveloperModeFilterin your environment. The configuration file is typically namedcom.day.cq.wcm.core.impl.WCMDeveloperModeFilter.cfg.json. The propertyenabledshould be set tofalseto disable the filter. If the file is absent orenabledis not set tofalse, Developer Mode is enabled by default in lower environments. - Use the Errors tab in the AEM editor side panel to view component-level issues. Only members of the administrators group can access Developer Mode.
- As a best practice, developers should use Developer Mode in lower environments to identify and resolve component errors before promoting code to higher environments.
After making a configuration change, test a page with a known component error on each affected author environment to confirm the expected error handling behavior.