Posts in Category "Installation"

Adobe CQ/AEM support tools available

We have recently published a package with support tools that can be useful to help diagnose issues encountered with Adobe Experience Manager.  As the tools project continues to mature, additional tools will be provided to ease the overall diagnosis and maintenance of CQ.

Overview of tools in 1st release:

  • Logs Viewer – Provides an easy way to download all CQ logs.  The tail functionality will open a new window and start tailing the log file.  Multiple log directories can be configured via Logs Tail Plugin.  The crx-quickstart/logs is used as default if configuration is not bound.  This tool can also be used with curl.  Allows you to package up all the logs in one single click making it easy to provide the logs when opening a Daycare ticket.  Detailed info here:
  • Tar PM Scan – Scans tar files and displays node path and size for each record.  This can be useful when analyzing abnormal workspace growth.  Large individual node sizes could indicate a flat hierarchy (i.e. a large child node list > 1000).  The same nodes appearing repeatedly in the scan could indicate a code issue or some other problem related to updating the same nodes repeatedly.  Detailed info here:
  • Thread Dumps Collection & Analysis – Takes thread dumps at regular intervals and saves them in a file under crx-quickstart/threads.  The page will also display a list of links to existing thread dump files.  The tool can use jstack, if it is installed on the system, or JVM MBean.  Detailed info here:
  • Content Compare & Import – Used to compare and import content differences from one CQ instance to another CQ instance.  This helps to ensure consistency across servers.  Detailed info here:

Download and install

The tools are supported for use with CQ5.5, AEM5.6 and later versions.  Here are the instructions to download and install the support tools:

VN:F [1.9.22_1171]
Was this helpful? Please rate the content.
Rating: 8.8/10 (11 votes cast)

CQ5.5 SP2.1: IllegalArgumentException: Servlet must not be null


If you are updating your CQ5.5 installation to SP2.1 on an application server you may notice the following exception in the logs:

12.11.2012 03:20:21.683 *ERROR* [CQSE HTTP Service] org.apache.felix.http.whiteboard Failed to register servlet
java.lang.IllegalArgumentException: Servlet must not be null
    at org.apache.felix.http.base.internal.service.HttpServiceImpl.registerServlet(
    at org.apache.felix.http.whiteboard.internal.manager.ServletMapping.register(
    at org.apache.felix.http.whiteboard.internal.manager.ExtenderManager.registerAll(
    at org.apache.felix.http.whiteboard.internal.manager.ExtenderManager.setHttpService(
    at org.apache.felix.http.whiteboard.internal.tracker.HttpServiceTracker.added(

After restarting the server you may notice the following errors in the log:

12.11.2012 03:22:14.621 *ERROR* [Thread-1] bindServlet: Unexpected problem initializing component Guice provision errors:
1) Error injecting method, java.lang.IllegalStateException: Servlet already initialized
    at org.apache.shindig.gadgets.servlet.ConcatProxyServlet.setConcatUriManager(
    while locating
Caused by: java.lang.IllegalStateException: Servlet already initialized
    at org.apache.shindig.common.servlet.InjectedServlet.checkInitialized(
    at org.apache.shindig.gadgets.servlet.ConcatProxyServlet.setConcatUriManager(

12.11.2012 03:23:10.151 *ERROR* [FelixStartLevel] [] The bindStats method has thrown an exception (java.lang.NullPointerException) java.lang.NullPointerException
    at sun.reflect.NativeMethodAccessorImpl.invoke0(Native Method)
    at sun.reflect.NativeMethodAccessorImpl.invoke(
    at sun.reflect.DelegatingMethodAccessorImpl.invoke(
    at java.lang.reflect.Method.invoke(
    at org.apache.felix.scr.impl.helper.BaseMethod.invokeMethod(
    at org.apache.felix.scr.impl.helper.BaseMethod.access$500(
    at org.apache.felix.scr.impl.helper.BaseMethod$Resolved.invoke(


These errors occur due to the files for the CQ Servlet Engine which are still deployed.  These files should not be included when deploying CQ to an application server, and there is a step in the SP2.1 release notes describing this.


  1. Go to /crx/explorer and open the Content Explorer
  2. Go to /libs/system/install, delete the cqse-httpservice-4.1.32.jar node and save your changes
  3. Restart the instance

These steps are listed in the release notes for SP2.1 when deploying to an application server:

VN:F [1.9.22_1171]
Was this helpful? Please rate the content.
Rating: 7.3/10 (3 votes cast)

CQ5.5: When to restart CQ after installing a service pack


If you are installing a service pack (SP) on top of CQ5.5 you will see a dialog recommending to restart the instance after you have run the SP installation:

Do not restart the instance at this point, as the contents of the service pack are still being extracted and installed in the background.  Restarting at this point could result in unknown problems, and you may have to repeat the SP installation.


You can monitor the log output in error.log and wait until the log no longer has new “BundleEvent STARTED” entries, before restarting the instance.  This usually takes 2 – 5 minutes depending on server specifications.

Monitoring log output may not be a good solution for large enterprise organisations which may have many CQ instances to update, and may need to use some kind of automated install script or process documentation.  In this case, you can either add a pause to the installation documentation (e.g. 15 or 30 minutes), or use a script to check for installation completion as described under 2 below.

1. Monitor the log output to figure out when to restart

The release notes for SP2.1 do contain instructions relating to this process (

Quickstart Install Process

  1. Login to Package Share and download SP2 package:
  2. Back in Package Manager – Install package
  3. After the package install is done – the PackageManager tells you to restart. DO NOT RESTART. The actual install of the package only starts now in background, given that the packages have been placed in /install folders. The best way to follow the process of the install is to tail the error.log
    The background install starts with “ Extracting day/cq550/update:cq-update-pkg:5.5.8” and stops with bundles been restarted – best seen by “BundleEvent STARTED” log entries.
  4. After the error.log goes quiet with “BundleEvent STARTED” messages
  5. Restart the instance
  6. The Welcome Screen should now show the updated Version String: Adobe CQ, Version Service Pack 2

2.  Use a script to automatically check for installation completion

You can use the script below which polls the server to check when the SP contents have been extracted, and then waits another few minutes for the relevant bundles to be started.  You can use the script on its’ own, or you could integrate it into existing scripts which you use to automatically install the CQ servicepack.

1. use a script similar to the following (designer for CQ5.5 SP2.1, you may need to adjust the cq-update-pkg version for other service packs)

until [ $res -eq 0 ]
    curl -u admin:admin -D- http://<cq_server_hostname>/etc/packages/day/cq550/update/ 2>/dev/null | head -1 | grep -q “HTTP/1.1 200”
    if [ $((count++ % 10)) -eq 0 ]
     echo “Waiting for service pack installation to finish…”
    sleep 1
sleep 300
echo “Service pack installation complete. You can restart the instance now.”

2. start the script in a terminal
3. install SP2.1
4. check the script output and await the completion message

5. restart the instance

reference: (39810/CQ5-22648)

VN:F [1.9.22_1171]
Was this helpful? Please rate the content.
Rating: 8.4/10 (9 votes cast)

CQ 5.5 Update 1: Service unavailable – AuthenticationSupport service missing. Cannot authenticate request.


CQ 5.5 Update 1 is now available on PackageShare.  If you have installed CQ 5.5 Update 1 you may encounter the following error in the error.log after restarting the CQ instance:

*ERROR* [0:0:0:0:0:0:0:1%0 [1340016598398] GET / HTTP/1.1] handleSecurity: AuthenticationSupport service missing. Cannot authenticate request.


After installing the Update 1 package, an info dialog appears which advises to “restart the instance”.  If you restart the instance immediately after the dialog appears, you will run into this problem.  Even after the dialog appears, the package keeps on installing behind the scenes.  This process is interrupted if the instance is restarted at this point.

You should wait until the installation has completed before restarting CQ5, checking the activity in error.log.  Once the error.log becomes quiet (after approx. 5 mins) it is safe to restart the instance.


After installing Update 1 check that all OSGi bundles have the status “ACTIVE” in the OSGi console.  Start any bundles that do not have the “ACTIVE” status and this should resolve the issue.

If the issue persists, you may have to reinstall CQ5 from a fresh copy, install the update 1 package, restart (wait until error.log shows no more activity) and finally reinstall your installed packages manually.

reference: (CQ5-18534)

VN:F [1.9.22_1171]
Was this helpful? Please rate the content.
Rating: 4.9/10 (14 votes cast)

CQ5.5: Upgrade recommendations and information

This information will be useful if you are planning to upgrade your CQ environment to CQ5.5. This information is intended as a supplement to the official upgrade documentation:

You should read these recommendations, and then follow the steps in the upgrading documentation, applying the added suggestions here as required.

Trial migration

It’s better to first run a dry-run migration on a clone of UAT (author & publish instances) to ensure that there are no major issues in the upgrade process. Check if there are any changes needed for your code to work on the upgraded version. In this case, change the code and ensure you have a consistent process for applying those changes. Identify any high risk areas in the code and plan for extended testing time on these areas following the upgrade.  Repeat the steps from scratch on the UAT clone so that you’ll be sure to have a consistent end-to-end process for the upgrade. Then proceed to upgrade all the environments: DEV, UAT & PROD.


  • Create a clone of the instance to upgrade.  You’ll perform the upgrade on the clone. It will be easier to rollback in case of problems.
  • Perform a full consistency check on the repository early.  Fix any problems before attempting the upgrade/migration.
  • Read the extensive list of “Tips and Troubleshooting” in the upgrade documentation and apply the recommended changes to avoid these common problems.
  • The code-base has to be frozen before the upgrade process and all the existing bugs closed. In case it’s not possible to close all bugs, keep a detailed list of them and double check them on the upgraded version.
  • Only do 1:1 migrations. Only introduce new product features for editors/business later. This will let you focus on the migration itself and any regressions.
  • Try to get dedicated hardware for all environments (PROD + staging), this gives you much more flexibility.
  • Involve Adobe consulting if required.  This will ensure a smooth migration process adhering to best practices.
  • Compile a list of all connected systems and involve those teams in the migration planning.  Ensure they have a short turn-around time in case of issues.
  • Purge workflow history (this speeds up the update process).
  • Make sure all workflow tasks are finished (none are running).
  • Make sure you have at least 1024MB Heap configured during update.
  • Clean all the logs to make it easier to isolate upgrade issues.
    • crx-quickstart/logs/*
    • crx-quickstart/server/logs/*


Tests should cover complete authoring workflows and not just the correct rendering of templates.

Check ACLs and permissions (especially when updating from 5.2.1).

Check Workflow models – check if any customizations were overwritten.

Check all forms and form actions (especially when updating from 5.3 or older).

Production upgrade

After performing the upgrade process on a UAT instance, once you are ready to upgrade the production instances, there shouldn’t be any major/unexpected issues. The code-base should already be frozen and in a good state, and you should freeze out content changes also. Only urgent changes should be applied to the content and the author team will need to keep track of all updated pages. These can then be moved later with a package.

1. Follow all the steps documented in the upgrade docs.

2. Sign-off the environments.

3. Migrate the latest content changes (if needed).

4. Switch the instances.

5. Delete all the dispatcher(s) cache.

It’s better to keep the old instances available for a while in case of problems not encountered during all the documented steps.  You should plan enough time for bug fixing following the production upgrade.

reference: (35335)

VN:F [1.9.22_1171]
Was this helpful? Please rate the content.
Rating: 6.3/10 (4 votes cast)