Upgrading from AEM 6.x to AEM 6.4

AEM 6.4 has been launched last year and you might be thinking of upgrading your AEM instances to the latest version of AEM which has a lot of new and powerful features in store.

AEM has provided better support for the upgrade. However, the upgrade process may be a little challenging if you are upgrading from CQ 5.x to AEM 6.4.

I have tried to list down the process of upgrading in this blog. Before starting the actual upgrade, I would like to highlight the below points:

  • AEM 6.0 introduced OAK repositories. Tar Persistence managers were replaced by the tar MK.
  • Although AEM 6.0 still supported the CRX2 repository, from AEM 6.1, they stopped supporting CRX2.
  • Now everything is based on OAK.
  • To migrate the repositories, we can make use of crx2oak tool.
  • This tool can even be used to migrate content within oak repositories. (For example, migrating content from segment MK to segment Tar MK.)
  • AEM 6.3 introduced a new format for segment Node Store. So, if the migration is to be done from 6.3, no repository migration is needed, otherwise, you will also need to migrate the repositories (for version older than 6.3).
  • Migrating repositories will need downtime. (for approx. 20 mins). A new version of CRX2Oak has been released to work with the new repositories formats.

To make sure that the upgrade procedure is fail-safe, we can follow the below steps:

Planning Upgrade

Proper planning is required to upgrade any of the previous AEM versions to AEM 6.4. Planning includes Author training, writing test cases for the upgrade procedure, Understanding the new changes around Architecture, estimating LOE using AEM provided Pattern Detector and then finally creating a project plan.

Note: It is possible to upgrade directly from AEM versions 6.0 and up to 6.4. Customers running 5.6.x and below need to upgrade first to version 6.0 or above, with 6.0(SP3) being recommended. Also, the new OAK Segment Tar format is used now for the Segment Node Store since 6.3, and repository migration to this new format is mandatory even for 6.0, 6.1 and 6.2.

Identifying architectural changes

Because AEM 6.x versions have been built on new specifications of operating systems or JVM’s, you should consider checking those if you are upgrading from pre-6.x versions. You will notice a significant difference around monitoring, maintenance, and backup and disaster recovery processes.

Estimate LOE using Pattern Detector

To estimate the overall level of efforts that may be needed for the upgrade can be calculated in two steps:

  1. First off, use a pattern detector to assess the complexity of the upgrades. The pattern detector can be run on the AEM 6.1, 6.2 and 6.3 instances. For each of these AEM versions, separate packages have been released by Adobe. Pattern detection allows you to identify all the deprecated API’s that you may have been using for your current versions of AEM.
  2. Prepare a test instance and there make an upgrade and do a quick smoke testing. Review the deprecated and removed features for both source and target versions as well as for the versions in between.



Upgrade snapshot

The following table describes what is needed and what is to be done to upgrade your AEM 6.x instance to 6.4.


Pre-Upgrade checklist

When you are going to start with the upgrade, make sure to once go through the following to ensure a smooth upgrade and easy rollback of your changes, should any failure occurs.

Task Action to be taken Comments
Ensure sufficient disk space When content migration takes place, your repository is copied in a new segment tar format, which may be potentially larger in size than the existing repository.
Back up AEM instance Take a full back up of the following items:

i.          Repository

ii.          Application Installation

iii.          Data store and Mongo instances (if applicable)

iv.          Other custom installations.

Back up changes under /etc Take a backup of the custom config nodes and content under /etc location.
Generate the file Upgrade will fail if you don’t have “” file under crx-quickstart/conf location.


If you don’t have this file, then restart the AEM with the jar file. file gets created when you first time start the AEM server by using the AEM jar.
Configure Workflow and Audit Log Purging If you have not already configured the workflow and audit log purging via their OSGI configs, please make sure to do that before starting the upgrade. If you don’t want to run them, then completely remove them.
Run the Pre-Upgrade Tasks  

Make sure that running the runAllPreUpgradeHealthChecks()

Completes successfully.


The Pre Upgrade Maintenance task package can be downloaded from the package share and be installed before starting the upgrade. (for versions older than 6.3)

For versions >6.3 it is available by default.


Disable Custom Login Modules Make sure to disable the custom login module if any, before starting the upgrades. In AEM versions that used CRX2 configuration was placed in the repository.xml file, while from AEM 6 onwards it is done in the Apache Felix JAAS Configuration Factory service via the Web Console.

Therefore, any existing configurations will have to be disabled and re-created for Apache Oak after the upgrade.

Remove Updates from the /install Directory Service packs, feature packs or hotfixes that have been deployed through the crx-quickstart/install directory on the local file system.

This will prevent 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 any standby instances before the upgrade. If any problem occurs during the upgrade, this can be used as an alternative.


After a successful upgrade, you need to rebuild the standby from the primary one.
Disable Custom Scheduled Jobs Disable any OSGi scheduled jobs that are included in your application code.
Execute Offline Revision Clean-up If you are using TarMK, complete offline revision clean-up so that repository migration and subsequent upgrade tasks can complete smoothly.
Execute Datastore Garbage Collection After revision clean-up, run DataStore Garbage Collection to remove unreferenced blobs in the data store.
Rotate Log Files Achieve your existing logs files. It will be easier for you to monitor and scan the new logs which will just have the entries related to the upgrade.

 Upgrading Code and Customization

As you have already run the pattern detector, you will be having a report of all the incompatibilities in your code. If there are no incompatibilities, then your code is compatible with AEM 6.4.

However, if there are any incompatibilities detected, you need to either

  • Run in compatibility mode and defer your development for new 6.4 features or compatibility
  • Decide to do development after the upgrade.

If you prefer to start code changes per the Pattern Detector report, you may follow the following steps:

Develop a new code for AEM 6.4

If you want to build new code base using new features in AEM 6.4 or pattern detector report compels you to do so, you can create a new branch or repository for the new code to be used in AEM 6.4.

Compile your code with 6.4 UBER jar

Once you have your code set up in the dedicated branch, you can then compile that against AEM 6.4 Uber jar. Make sure you have an entry for this version of Uber Jar in your code’s pom file. Once you have made changes in the POM file, compile the code against the latest Uber jar.

Update AEM Customizations 

Any customization or extensions to AEM should be updated/validated to work in 6.4 and added to the 6.4 code base. Includes UI Search Forms, Assets Customization, anything using /mnt/overlay

Deploy the compiled code to AEM 6.4

Deploy the latest compiled code to AEM 6.4 and install the latest content package to this environment.

QA Validation and bug fix

Let QA validate the newly deployed code. And the developers can then start on the bug fixing if any.

Upgrade Preparation

You can take a back-up of your local author server. Make sure you disable authoring on the author environment before starting the process. Disable the replication agents, stop the cold stand by (for the production servers), and run the pre-upgrade maintenance tasks.



Upgrade Execution

Now run the in-place upgrade using the following steps:

  1. Stop running the instance.
  2. Replace the old AEM jar with the new AEM 6.4 jar. (outside the crx-quickstart folder)
  • Unpack the new jar by using the command below:

java -Xmx4096m -jar {jar file name}.jar -unpack


Migrate Repository

If you are upgrading from AEM 6.2 or below, then this step is required. For AEM6.3 this is not required.

Adobe provides a tool called CRX2OAK for repository migration from TarMK to Oak Segment Tar.

If you are using MongoMk storage, then repository migration is not required.

In order to execute the oak run tool, use the following command:

java -Xmx4096m -jar aem-quickstart.jar -v -x crx2oak -xargs — –load-profile <<YOUR_PROFILE>> <<ADDITIONAL_FLAGS>>

The above commnads uses  -x crx2oak option, which basically execute the oak run tool.

Please note that :

  1. If you are performing the upgrade on a Windows system where Java memory mapping is not handled correctly, please add the –disable-map parameter to the command.
  2. If you are using Java 7, add the -XX:MaxPermSize=2048m parameter just after the -Xmx parameter


CRX2OAK Migration Tool

Shut down your running AEM 6.2 instance and do the compaction.


Once the compaction is successfully completed, prepare for the migration. You will need CRX2OAK jar for the repository migration. You can keep the jar at any place to run. You will need the path to the old repository as well as the path to the new one.


Run the following command for the migration:
java -jar crx2oak.jar segment-old: <<old location>> <<new location>>


Once the migration is successful you will see something like:


After the successful migration, it is the time to prepare the AEM 6.4 specific quick-start file. Get the 6.4 jar and unpack that.


Once unpacking is done, run the AEM jar with the following command:

Java -jar aem-quickstart.jar


The start-up may take a bit longer. Wait for the start-up to complete, and it will launch the browser automatically


Check if the system is up and all the bundles are in Active state in the system console.


Install the upgraded code. (If any)

Note: If you face repository service missing exception after upgrading, then first delete the indexes node and then start the server. Also, check if all the bundles are in the active state. If not then wait until all of them start.

About The Author