Pre-Upgrade Maintenance Tasks pre-upgrade-maintenance-tasks

Last update: September 9, 2026

Applies to:
Experience Manager 6.5 LTS

Topics:
Upgrading

CREATED FOR:

Admin

Before beginning your upgrade, it is important to follow these maintenance tasks to ensure that the system is ready and can be rolled back should issues occur:

Index Definitions index-definitions

Make sure that you have installed the required index definitions released with the latest AEM 6.5 Service Pack. (Refer to AEM 6.5 servicepack release notes for more information).

Ensure Sufficient Disk Space ensure-sufficient-disk-space

When executing the upgrade, ensure that there is enough disk space.

Fully Back Up AEM fully-back-up-aem

AEM should be fully backed up before beginning the upgrade. Make sure to back up your repository, application installation, datastore, and Mongo instances if applicable. For more information on backing up and restoring an AEM instance, see Backup and Restore.

Check for Stale Pre-Upgrade Backups check-stale-pre-upgrade-backups

Before an upgrade, AEM backs up certain paths (such as /etc/tags) under /var/upgrade/PreUpgradeBackup/<timestamp>, then restores them once the upgrade completes. Each backup node has a merge status property: INIT means the backup was created but never merged back, while COMPLETED means the merge finished successfully.

If a backup from a previous upgrade (e.g. from 6.4 to 6.5) is left in INIT status, the latest upgrade (from 6.5 to 6.5 LTS) restores that old, unmerged backup. This can silently reintroduce stale or outdated content that no longer matches the current repository state, leading to unexpected issues after the upgrade completes.

To avoid this, before starting the upgrade:

Using CRXDE Lite (/crx/de/index.jsp), check the source instance for any pre-existing nodes under /var/upgrade/PreUpgradeBackup/.
Inspect the merge status property of each backup node found.
If a node is found in INIT status from a previous upgrade, review its contents and clean it up — either delete it or explicitly merge it — before proceeding. Doing so ensures the upgrade creates a fresh, accurate backup instead of silently restoring stale data.

Generate The quickstart.properties File generate-quickstart-properties

When starting AEM from the jar file, a quickstart.properties file is generated under crx-quickstart/conf. If AEM has only been started with the start script in the past, this file is not present and the upgrade fails. Make sure to check for the existence of this file and restart AEM from the jar file if it is not present.

Configure Workflow and Audit Log Purging configure-wf-audit-purging

The WorkflowPurgeTask and com.day.cq.audit.impl.AuditLogMaintenanceTask tasks require separate OSGi configurations and cannot work without them. If they fail during pre-upgrade task execution, missing configurations is the most likely reason. Therefore, make sure to add OSGi configurations for these tasks or remove them altogether from the pre-upgrade optimization tasks list if you do not wish to run them. Documentation for configuring workflow purging tasks can be found at Administering Workflow Instances and audit log maintenance task configuration can be found at Audit Log Maintenance in AEM 6.

Install, Configure, and Run The Pre-Upgrade Tasks install-configure-run-pre-upgrade-tasks

Pre-upgrade maintenance tasks that before had to be performed manually are being optimized and automated. The pre-upgrade maintenance optimization enables a unified way to trigger these tasks and be able to inspect their result on demand.

How to Use It how-to-use-it

The PreUpgradeTasksMBean OSGI component comes preconfigured with a list of pre-upgrade maintenance tasks that can be run all at once. You can configure the tasks by following the below procedure:

Go to the Web Console by browsing to https://serveraddress:serverport/system/console/configMgr
Search for “preupgradetasks”, then click the first matching component. The full name of the component is com.adobe.aem.upgrade.prechecks.mbean.impl.PreUpgradeTasksMBeanImpl
Modify the list of maintenance tasks that must be run as shown below:

Below is a description of the run mode that each maintenance task is designed for.

Task

Notes

WorkflowPurgeTask

Must configure the Adobe Granite Workflow Purge Configuration OSGi before running.

GenerateBundlesListFileTask

RevisionCleanupTask

com.day.cq.audit.impl.AuditLogMaintenanceTask

Must configure the Audit Log Purge Scheduler OSGi configuration before running.

Default Configuration of the Pre-Upgrade Health Checks default-configuration-of-the-pre-upgrade-health-checks

The PreUpgradeTasksMBeanImpl OSGI component comes pre-configured with a list of pre-upgrade health check tags to execute when the runAllPreUpgradeHealthChecks method is called:

system - the tag used by the granite maintenance health checks
pre-upgrade - a custom tag that could be added to all the health checks that you can set to run before an upgrade

MBean Methods

The managed bean functionality can be accessed using the JMX Console.

You can access the MBeans by:

Going to the JMX Console at https://serveraddress:serverport/system/console/jmx
Search for PreUpgradeTasks and click the result
Select any method from the Operations section and select Invoke in the following window.

Below is a list of all the available methods that the PreUpgradeTasksMBeanImpl exposes:

Method Name

Type

Descriptio

runAllPreUpgradeTasks()

ACTION

Runs all the pre-upgrade maintenance tasks in the list.

runPreUpgradeTask(preUpgradeTaskName)

ACTION

Runs the pre-upgrade maintenance task with the name given as the parameter.

getPreUpgradeTaskLastRunTime(preUpgradeTaskName)

ACTION

Displays the exact running time of the pre-upgrade maintenance task with the name given as the parameter.

getPreUpgradeTaskLastRunState(preUpgradeTaskName)

ACTION

Displays the last running state of the pre-upgrade maintenance task with the name given as the parameter.

runAllPreUpgradeHealthChecks(shutDownOnSuccess)

ACTION

Runs all the pre-upgrade health checks and saves their status in a file named preUpgradeHCStatus.properties in the sling home path. If shutDownOnSuccess is set to true, the AEM instance is shut down, but only if all the pre-upgrade health checks have an OK status. The properties file is used as a precondition for any future upgrade, and the upgrade process is stopped if the pre-upgrade health check execution failed. If you want to ignore the result of the pre-upgrade health checks and launch the upgrade anyway, you can delete the file.

detectUsageOfUnavailableAPI(aemVersion)

ACTION

Lists all the imported packages that are no longer satisfied when upgrading to the specified AEM version. The target AEM version must be given as a parameter.

NOTE

The MBean methods can be invoked via:

The JMX Console
Any external application that connects to JMX
cURL

Remove Updates From The /install Directory remove-updates-install-directory

NOTE

Only remove packages from the crx-quickstart/install directory AFTER shutting down the AEM instance. This step is one of the last before starting the in-place upgrade procedure.

Remove any service packs, feature packs, or hotfixes that were deployed through the crx-quickstart/install directory on the local file system. Doing so prevents the inadvertent installation of old hotfixes and service packs on top of the new AEM version after the update has completed.

Stop Any Cold Standby Instances stop-tarmk-coldstandby-instance

If using TarMK cold standby, stop any cold standby instances. Doing so guarantees an efficient way to come back online if there are issues in the upgrade. After the upgrade has completed successfully, the cold standby instances must be rebuilt from the upgraded primary instances.

Disable Custom Scheduled Jobs disable-custom-scheduled-jobs

Disable any OSGi scheduled jobs that are included in your application code.

Execute Offline Revision Cleanup execute-offline-revision-cleanup

NOTE

This step is only necessary for TarMK installations

If using TarMK, you should run Offline Revision Cleanup before upgrading. Doing so makes the repository migration step and subsequent upgrade tasks execute much faster and helps to ensure that Online Revision Cleanup can execute successfully after the upgrade has completed. For information on running Offline Revision Cleanup, see Performing Offline Revision Cleanup.

Execute Datastore Garbage Collection execute-datastore-garbage-collection

After running revision cleanup on CRX3 instances, you should run Datastore Garbage Collection to remove any unreferenced blobs in the data store. For instructions, see the documentation on Data Store Garbage Collection.

Rotate Log Files rotate-log-files

Adobe recommends archiving your current log files before beginning your upgrade. Doing so makes it easier to monitor and scan your log files during and after the upgrade to identify and resolve any issues that may occur.

recommendation-more-help

experience-manager-65-lts-help-main-toc