DocumentationExperience Cloud KCS

AEM as a Cloud Service: Resolving PackageOverlaps warning for Oak Index diff.json

Last update: October 19, 2026

✨ This content is AI generated and could be inaccurate. Generative AI Terms

This article explains how to resolve conflicts and Code Quality warnings in Adobe Experience Manager as a Cloud Service when multiple packages deliver different versions of the Oak Index diff.json file.

Description description

Environment

Adobe Experience Manager as a Cloud Service (all versions)

Symptoms

  • Cloud Manager’s Code Quality step reports a PackageOverlaps warning for the path /oak:index/diff.index.
  • Multiple sub-projects deliver their own ui.apps/src/main/content/jcr_root/_oak_index/diff.index/diff.json file.
  • Each package includes a different diff.json under the same repository path.
  • The last-installed package overwrites the others, resulting in only a subset of intended Oak index definitions being present.
  • Indexes may be alternately created and removed on deployments, depending on package installation order.

Cause

Multiple packages delivering different versions of the same diff.json file under /oak:index/diff.index leads to file overwrites and Code Quality overlap warnings. Only one canonical delivery of the Diff Index file is supported in AEM as a Cloud Service.

Resolution resolution

Follow the steps below to resolve the issue:

  1. Designate a single sub-project or package to own and deliver the canonical diff.json file under ui.apps/src/main/content/jcr_root/_oak_index/diff.index/diff.json.
  2. Remove the /oak:index/diff.index filter and associated diff.json delivery from all other sub-projects or packages.
  3. Ensure the canonical diff.json contains all required Oak index definitions from all sub-projects.
  4. Build the consolidated package and verify that it includes all necessary index definitions.
  5. Confirm that other packages no longer deliver the /oak:index/diff.index node or diff.json file.
  6. Deploy the updated packages to a non-production environment (such as DEV or QA).
  7. Ensure that the PackageOverlaps warning no longer appears in the Code Quality report.
  8. In the target environment, verify that all required indexes are present and functioning as expected.
recommendation-more-help
experience-cloud-kcs-help-kbarticles