Documentation

Assets don’t move from upload to target folder in AEMaaCS

Last update: Wed May 27 2026 00:00:00 GMT+0000 (Coordinated Universal Time)

Assets remain stuck in the upload or staging folder when a custom workflow fails to move them to the target folder due to repository commit conflicts. Redesign the workflow to avoid large parallel commits and split metadata updates into a separate post‑processing workflow to resolve the issue.

Description description

Environment

  • Adobe Experience Manager as a Cloud Service – Assets
  • Author environment, deployed via Cloud Manager
  • Custom asset‑move workflow triggered by a launcher or scheduled job

Issue/Symptoms

  • Assets remain in the upload or staging folder and do not appear in the target folder.

  • A custom asset-move workflow is triggered correctly (for example, by a cron-like launcher) but:

    • Takes a very long time to complete, or
    • Ends with repeated failures and retries.

  • No errors are reported for the launcher itself; failures occur in the custom move step.

  • A large number of workflow instances (for example, 10,000+ running instances) accumulate for the same workflow model.

  • The AEM error log shows commit failures with concurrent change conflicts, for example:

    code language-none 
    org.apache.sling.api.resource.PersistenceException: Unable to commit changes to session      at com.example.aem.core.workflows.MoveToTarget.execute(MoveToTarget.java:xx)    Caused by: javax.jcr.InvalidItemStateException:      OakState0002: Conflicting concurrent change on branch commits

  • Post-processing behavior (such as updating media titles, uploader information, or Dynamic Media flags) is delayed or intermittent because assets do not reach the target folder reliably.

Cause

  • In the affected implementations, the custom asset-move step was changed to:

    • Batch many asset moves into a single large JCR session and commit, and
    • Run this logic in parallel across many workflow instances (for example, via a launcher running every few minutes while previous runs are still active).

  • Under load, this design leads to:

    • Conflicting concurrent branch commits in the Oak repository (OakState0002), causing the commit to fail and the workflow job to be retried.
    • A race where the asset is moved first and metadata at the original path is updated later, so the metadata update fails or is skipped.

  • The problem is a repository-level contention issue in custom workflow code, not a malfunction of the launcher or AEM’s built-in asset processing.

Resolution resolution

To restore reliable asset movement and prevent commit conflicts, follow these steps:

  1. Remove or revert any single large commit batching so the custom asset-move step no longer moves and updates multiple assets in a single save() or commit(), and avoid designs where hundreds of assets are moved in one transaction.
  2. Refactor the move step so each asset, or a very small batch, is moved to the target location and committed immediately (for example, with session.save() or resourceResolver.commit()), and ensure the step is idempotent per asset and can safely handle retries, optionally catching InvalidItemStateException or PersistenceException and implementing bounded retries with logging.
  3. Split the move and metadata or post-processing logic into separate workflows by keeping the move workflow focused on selecting valid assets and moving them from the upload or staging folder to the target folder, and configuring a separate post-processing workflow on the target folder that updates metadata and custom properties (such as Dynamic Media flags or fields used by downstream systems) and runs via the post-processing (auto-start) workflow mechanism after asset processing is complete.
  4. Limit concurrency for the move workflow by reviewing the job queue configuration for the workflow’s Sling job topic, reducing the maximum number of parallel jobs where possible, and ensuring the launcher doesn’t start new large runs while previous runs are still active or retrying.
  5. Keep workflow instances under control by configuring workflow purge (for example, with the com.adobe.granite.workflow.purge.Scheduler configuration) so completed instances of the custom model are purged regularly and don’t accumulate.
  6. Validate behavior after these changes by uploading a controlled test set of assets to the upload or staging folder, confirming that assets move reliably to the target folder within the expected time, that post-processing workflows in the target folder complete successfully and update metadata promptly, and that logs no longer show frequent OakState0002 commit conflicts related to the custom move step.

Notes:

  • This issue arises from how custom workflows interact with the AEM as a Cloud Service repository under concurrency, not from a malfunction of the launcher or AEM’s built-in asset processing.
  • By redesigning the workflow to commit per asset (or small batch) and moving metadata or property updates into a separate post-processing workflow in the target folder, you reduce commit contention, eliminate the move/metadata race, and restore stable, timely movement of assets from the upload folder to the target folder.
recommendation-more-help
3d58f420-19b5-47a0-a122-5c9dab55ec7f