DocumentationExperience Cloud KCS

Package installation fails in AEM environments

Last update: July 16, 2026

AEM package installation fails when packages include immutable paths, invalid ZIP structure, install hooks, or affected SDK versions. Diagnose the installation error and follow the appropriate resolution steps to install the package successfully.

Description description

Environment

  • Adobe Experience Manager as a Cloud Service
  • AEM Managed Services
  • Adobe Developer App Builder

Issue/Symptoms

  • Error during upload indicating that the archive is not a valid content package because jcr_root is missing.
  • Package validation errors during installation.
  • Installation blocked because the package contains immutable repository paths.
  • Embedded packages inside an all package do not install automatically.
  • Package download failures caused by invalid package names.
  • Installation failures related to missing install hook classes.

Cause

Installation failures occur when the package structure is invalid, the package includes immutable repository paths, package names contain unsupported characters, install hooks are used where they are unsupported, or the deployment relies on an SDK version affected by a regression.

Resolution resolution

To resolve this issue, follow these steps:

  1. Identify the installation error by reviewing the Package Manager message or logs.
  2. If the package is not recognized as a content package, verify that META-INF and jcr_root exist at the ZIP file’s top level. Recreate the package if necessary.
  3. If the package contains immutable repository paths, deploy the code through the appropriate deployment pipeline instead of installing it directly through Package Manager.
  4. If embedded packages do not install automatically, verify the SDK version and upgrade to an SDK version that includes the regression fix.
  5. Remove install hooks when deploying to environments that do not support them. For supported environments, ensure all required dependencies are installed.
  6. Update package names to remove unsupported characters and rebuild the package before deploying again.
  7. Validate the installation by confirming that installation errors no longer appear and embedded packages install correctly when applicable.
recommendation-more-help
experience-cloud-kcs-help-kbarticles