Resolve AEM as a Cloud Service pipeline failures during index updates
This article explains how to resolve failures in the AEM as a Cloud Service Cloud Manager pipeline that occur during the index update step after deploying custom or extended index definitions. The guidance covers common causes and actionable steps to help ensure successful deployments.
Description description
Environment
Adobe Experience Manager as a Cloud Service (AEMaaCS)
Issue/Symptoms
- Pipeline failures with errors indicating issues retrieving new index definitions
- Validation warnings related to index configuration files
Cause
The root causes often include mismatches between custom index definitions and the out-of-the-box (OOTB) index versions in the target environment, incomplete or invalid Tika configurations, or improper index naming and versioning practices.
Resolution resolution
Follow the steps below to resolve the issue:
- Compare your custom index definitions with the OOTB index definitions in the target environment. Obtain the latest OOTB index definition (for example, damAssetLucene-14) from an AEM as a Cloud Service environment running the same or a newer release than the target environment.
- Merge your custom changes into the latest OOTB definition and assign an appropriate versioned custom name (for example, damAssetLucene-14-custom-2). Do not assume the OOTB version in the development environment matches the version in other environments.
- Validate the Tika configuration in the custom index definition. Ensure the complete Tika subtree is present and valid, including the tika/ folder, config.xml, jcr:content, jcr:data, and jcr:mimeType set to application/xml. Avoid partial overrides or empty config.xml nodes.
- Follow AEM as a Cloud Service naming conventions for custom indexes. For fully custom indexes, use a unique custom name and version (for example, -custom-1). For extensions of OOTB indexes, use the OOTB naming and versioning pattern. Do not rename or delete deployed index nodes directly in the Cloud environment.
- Confirm that all index definitions are located under ui.apps/src/main/content/jcr_root/_oak_index and are included in the application code package, not a mutable content package. Ensure the package metadata includes allowIndexDefinitions=true and noIntermediateSaves=true. All index definitions must use Cloud-compatible Lucene configuration and supported async settings (such as
[async],[async,nrt], or[fulltext-async]). - Deploy the revised package to a lower environment and verify that the deployment completes successfully, the expected index definitions are present, and queries use the intended indexes.
- To retire old index definitions, do not rename or delete index nodes directly. Instead, handle retirement as a separate code change through Cloud Manager. Removing entries from filter.xml alone does not remove deployed index data. Use a subsequent compliant index definition to disable the previous index and make it eligible for periodic cleanup.
After completing these steps, rerun the pipeline and verify that the deployment succeeds and the intended indexes are active.
recommendation-more-help
experience-cloud-kcs-help-kbarticles