How to start AEM in debug mode? Adobe Experience Manager start guide

There are multiple approaches to start or tune Adobe Experience Manager (AEM) instance in debug mode. we will cover few of them in this tutorial.

1. We could start AEM using the command prompt by using the below command line.

 java -jar aem63-author-p4502.jar -debug <port#>

2. Another way to start or tune AEM instance in debug mode is, we could update the start.bat file and start AEM by clicking on the start.bat file in crx-quickstart folder. To do so we have to do the following.

• First we need to update the start file; go to \crx-quickstart\bin\start.bat and append this command "-debug -Xnoagent -Djava.compiler=NONE -Xrunjdwp:transport=dt_socket,server=y,suspend=n,address=<port#>" with line 25, default JVM options.
• Save the file
•  Now double click on the start.bat file to start your AEM instance.

After changes, your start.bat file will look like following.

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85

@echo off :: This script configures the start information for this server. :: :: The following variables may be used to override the defaults. :: For one-time overrides the variable can be set as part of the command-line; e.g., :: :: SET CQ_PORT=1234 & ./start.bat :: setlocal ::* TCP port used for stop and status scripts if not defined CQ_PORT set CQ_PORT=4502 ::* hostname of the interface that this server should listen to :: if not defined CQ_HOST set CQ_HOST= ::* runmode(s) ::* will not be used if repository is already present if not defined CQ_RUNMODE set CQ_RUNMODE=author ::* name of the jarfile :: if not defined CQ_JARFILE set CQ_JARFILE= ::* default JVM options if not defined CQ_JVM_OPTS set CQ_JVM_OPTS=-Xmx2048m -XX:MaxPermSize=512M -Djava.awt.headless=true -debug -Xnoagent -Djava.compiler=NONE -Xrunjdwp:transport=dt_socket,server=y,suspend=n,address=30303 ::* ------------------------------------------------------------------------------ ::* authentication ::* ------------------------------------------------------------------------------ ::* when using oak (crx3) authentication must be configured using the ::* Apache Felix JAAS Configuration Factory service via the Web Console ::* see http://jackrabbit.apache.org/oak/docs/security/authentication/externalloginmodule.html ::* use jaas.config (legacy: only used for crx2 persistence) :: if not defined CQ_USE_JAAS set CQ_USE_JAAS=true ::* config for jaas (legacy: only used for crx2 persistence) if not defined CQ_JAAS_CONFIG set CQ_JAAS_CONFIG=etc\jaas.config ::* ------------------------------------------------------------------------------ ::* persistence mode ::* ------------------------------------------------------------------------------ ::* the persistence mode can not be switched for an existing repository set CQ_RUNMODE=%CQ_RUNMODE%,crx3,crx3tar :: set CQ_RUNMODE=%CQ_RUNMODE%,crx3,crx3mongo ::* settings for mongo db :: if not defined CQ_MONGO_HOST set CQ_MONGO_HOST=127.0.0.1 :: if not defined CQ_MONGO_PORT set CQ_MONGO_PORT=27017 :: if not defined CQ_MONGO_DB set CQ_MONGO_DB=aem6 ::* ------------------------------------------------------------------------------ ::* do not configure below this point ::* ------------------------------------------------------------------------------ chdir /D %~dp0 cd .. if exist conf\controlport del conf\controlport if not defined CQ_JARFILE for %%X in (app\*.jar) do set CQ_JARFILE=%%X for %%* in (.) do set CurrDirName=%%~n* cd .. set START_OPTS=start -c %CurrDirName% -i launchpad if defined CQ_PORT set START_OPTS=%START_OPTS% -p %CQ_PORT% if defined CQ_RUNMODE set CQ_JVM_OPTS=%CQ_JVM_OPTS% -Dsling.run.modes=%CQ_RUNMODE% if defined CQ_HOST set CQ_JVM_OPTS=%CQ_JVM_OPTS% -Dorg.apache.felix.http.host=%CQ_HOST% if defined CQ_HOST set START_OPTS=%START_OPTS% -a %CQ_HOST% if defined CQ_MONGO_HOST set START_OPTS=%START_OPTS% -Doak.mongo.host=%CQ_MONGO_HOST% if defined CQ_MONGO_PORT set START_OPTS=%START_OPTS% -Doak.mongo.port=%CQ_MONGO_PORT% if defined CQ_MONGO_DB set START_OPTS=%START_OPTS% -Doak.mongo.db=%CQ_MONGO_DB% if defined CQ_USE_JAAS set CQ_JVM_OPTS=%CQ_JVM_OPTS% -Djava.security.auth.login.config=%CQ_JAAS_CONFIG% set START_OPTS=%START_OPTS% -Dsling.properties=conf/sling.properties if exist newTaskList.txt del newTaskList.txt if exist oldTaskList.txt del oldTaskList.txt tasklist /FI "IMAGENAME eq java.exe" /NH > oldTaskList.txt start "CQ" cmd.exe /C java %CQ_JVM_OPTS% -jar %CurrDirName%\%CQ_JARFILE% %START_OPTS% :: removing the delay until CQ-4202186 is solved :: timeout /T 1 /NOBREAK >nul tasklist /FI "IMAGENAME eq java.exe" /NH > newTaskList.txt java -cp %~dp0 GetProcessID oldTaskList.txt newTaskList.txt java.exe > %CurrDirName%\conf\cq.pid if exist newTaskList.txt del newTaskList.txt if exist oldTaskList.txt del oldTaskList.txt

Once you have done with the above changes and started your aem in debug mode then you have to configure debugger in your IDE (Eclipse or IntelliJ). To configure the debugger with your local AEM instance please follow this article. Remote debugger in eclipse

Configure and start remote debugger in Eclipse

Set the remote debugger configuration in Eclipse, to debug the running application code and identify the code issues.

Step 1: Open the Debug perspective from tool bar. if you don't see debug perspective option in your toolbar, then open the perspective from this path in Eclipse. 

Windows >> Perspective >> Open perspective >> Others >> Debug  

1. Click on the perspective drop-down option very next to bug symbol.
2. Select the option Debug configuration

Debug Configuration in Eclipse

Step 2: Debug Configuration will open a new window(below is the screenshot).

1. Click on Remote Java Application option from left side rail.
2. Click on the New Launch configuration(new configuration) button. As shown in the screenshot below.

Remote Java Application setup

Step 3: Once you click on new configuration button, a configuration setup option will appear right side on same window. Switch to connect tab, if you are not on the connect tab by default.

1. In Name section, please provide a valid name.
2. In Connection Properties section specify the host and port on which your application is running. 
   e.g. 
   Host: localhost
   Port: 30303 (default AEM debug mode port)
3. Project: Select the core folder of your project.
4. Connection type: Keep it as Standard.

Debugger remote connection setup

Step 4: Now switch to source tab, next to connect and configure your Java project. Below is the screenshot.

1. Switch to source tab
2. Click on Add option
3. Select Java Project option
4. Hit Ok button
5. Select your project 
6. Hit Ok button
7. After successful selection your project get added in the source section.  

Debug project setup in Eclipse

You have successfully setup the debugger with your remote application. Now run or tune your application in debug mode and start the debugger in Eclipse from debug perspective to listen the request from your application server to Eclipse.