Documentation

TagManager.resolve returns null on AEM as a Cloud Service Publisher

Last update: Mon Sep 22 2025 00:00:00 GMT+0000 (Coordinated Universal Time)

On AEM as a Cloud Service Publisher environment, calls to TagManager.resolve returns null, but the same logic works correctly on AEM 6.5 or the Author environment. The system defaults to /etc/tags for tag resolution rather than the standard AEMaaCS path: /content/cq:tags. To fix this, update the OSGi configuration to disable legacy support and remove the /etc/tags node from both Author and Publisher environments.

Description description

Environment

Adobe Experience Manager (AEM) as a Cloud Service - Sites

Issue/Symptoms

  • Servlet code uses:

    code language-none 
    TagManager tagManager = request.getResourceResolver().adaptTo(TagManager.class);    Tag tag = tagManager.resolve("/content/cq:tags/...");

    TagManager resolves as null only on Publisher, not on Author.

  • Log file shows:

    com.day.cq.tagging.impl.JcrTagManagerFactoryImpl Using /etc/tags as root path for tags

    This indicates the system is defaulting to /etc/tags.

  • Tags exist under /etc/tags on Publisher, while /content/cq:tags is properly configured on Author.

Root Cause

The presence of tags under /etc/tags on the Publisher causes AEM to default to the legacy /etc/tags path.

Resolution resolution

To resolve the issue:

  1. Set the OSGi configuration property legacySupport.enabled.name to false for the service com.day.cq.tagging.impl.JcrTagManagerFactoryImpl(Day CQ Tagging Service). This ensures AEM uses /content/cq:tags as the root path.

  2. Ensure the /etc/tags node is either missing or empty on both Author and Publisher environments.

  3. To clean up the Publisher:

    1. Create a blank content package that includes /etc/tags but without any child nodes.
    2. Install the package on Author and replicate it to Publisher. This will remove /etc/tags from both environments.

  4. Alternatively, delete the /etc/tags node directly from Publisher by sending a Delete  action request from the Author Distribution UI.

As a result:

  • AEM logs should show: com.day.cq.tagging.impl.JcrTagManagerFactoryImpl Using /content/cq:tags as root path for tags
  • TagManager.resolve will correctly use tags at /content/cq:tags.
recommendation-more-help
3d58f420-19b5-47a0-a122-5c9dab55ec7f