Author mode error handling differences in AEM Sites environments
If author mode shows inline component errors on one AEM Sites environment but fails to render the page on another, check the WCMDeveloperModeFilter configuration for each environment. This filter is enabled by default on every author instance and disabled by default on every publish instance; differences between author tiers usually come from custom configuration, not platform defaults.
Description description
In Adobe Experience Manager Sites, the same page can display different error handling behavior in author mode across environments. On some author instances, component-level failures are shown inline and the rest of the page continues to render. On others, similar errors can cause the entire page to fail to render or become un-authorable, even though the codebase is identical.
Environment
Adobe Experience Manager as a Cloud Service (all versions)
Issue/Symptoms
- On one author instance, component errors display inline and the page continues to load.
- On another author instance, the same underlying error causes 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 comes from the configuration of WCMDeveloperModeFilter (also known as the CQ WCM Debug Filter). By default, AEM enables this filter on every author instance and disables it on every publish instance, regardless of environment tier. When enabled, the filter catches component exceptions and renders the page with inline error messages. When disabled, a component exception can cause the entire page to fail.
If you see this filter behaving differently between author environments of different tiers (for example, dev author vs. stage or production author), check for tier-specific OSGi configuration, such as a config.author.stage or config.author.prod folder, that explicitly overrides the default for that tier. This is a project-level customization, not out-of-the-box AEM behavior.
Resolution resolution
Follow these steps to resolve the issue.
- Review how
WCMDeveloperModeFilterbehaves by default: it is enabled on every author instance, where it catches component exceptions and displays inline error messages so the rest of the page renders, and disabled on every publish instance, where a component exception can cause the entire page to fail. - Keep Developer Mode enabled on author instances so component errors surface and get fixed early, since disabling it there can hide component-level failures until code reaches a later stage.
- Check the Developer Mode configuration for the environment in question by reviewing the OSGi configuration for
com.day.cq.wcm.core.impl.WCMDeveloperModeFilter, typically incom.day.cq.wcm.core.impl.WCMDeveloperModeFilter.cfg.json, including any tier-specific run mode folder such asconfig.author.stageorconfig.author.prod; if theenabledproperty is set tofalse, the filter is disabled for that scope, and if the file is absent orenabledis not set tofalse, the filter uses the AEM default. - 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, resolve component errors on a dev or lower author environment before promoting code, so the same errors do not surface unexpectedly on a higher-tier author instance.
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.