AEM debugging tips with Eclipse IDE
Debugging an Adobe Experience Manager application involves more than placing a breakpoint in a Java class. AEM combines OSGi services, Sling requests, repository content, servlets, workflows, client libraries, and external integrations. Eclipse IDE can bring these moving parts into one practical workflow, provided the local runtime and project configuration are aligned.
The most effective approach is to make each debugging session deliberate. Confirm that the deployed bundle matches the source code, identify the request path before stepping through methods, and use logs and repository tools alongside the Java debugger. This reduces the time spent investigating symptoms caused by stale code, incorrect run modes, or missing configuration.
The CIRCUIT conference community is a useful reference point for this kind of work because its sessions brought Java developers, AEM architects, front-end specialists, and systems engineers together around real implementation concerns. The same habits that help during a technical workshop—observing the full system, isolating variables, and sharing reproducible findings—apply to daily AEM development.
Prepare Eclipse and the local AEM runtime
Start with a clean relationship between Eclipse, Maven, and the AEM instance. Import the project as a Maven project, confirm that the generated source folders are recognized, and check that the Java compiler level matches the version supported by the target AEM release. A mismatch can produce misleading stack traces or prevent remote debugging from attaching correctly.
Run AEM with the Java Debug Wire Protocol enabled. A typical local startup configuration exposes a debug port such as 8000, but the exact command depends on the AEM version and the way the author or publish instance is launched. Attach Eclipse through a Remote Java Application configuration, select the correct project, and verify that the connection reaches the intended instance.
Before investigating a defect, deploy the current bundle and inspect its state in the OSGi Web Console. A bundle that is installed but unresolved can point to missing package imports, version conflicts, or an unavailable service. If the debugger cannot find a source location, compare the deployed bundle timestamp and symbolic name with the project you are editing.
Set breakpoints where requests actually travel
A breakpoint in a model or service is useful only when the incoming request reaches that class. Begin with the URL, HTTP method, selectors, extension, and suffix. In AEM, a request may be handled by a resource type, servlet registration, Sling Model exporter, filter, or component script. Understanding that resolution path is often faster than stepping through unrelated framework code.
Conditional breakpoints are especially valuable for high-traffic author instances. Instead of stopping for every request, add a condition based on a content path, selector, component property, or user identifier. Eclipse also supports hit counts, which can help when a defect appears only after repeated calls or during a particular workflow transition.
Use method breakpoints sparingly. They can slow an application significantly, especially when placed on frequently invoked getters, OSGi lifecycle methods, or repository access code. Line breakpoints inside the suspected branch generally provide clearer results and keep the local AEM instance responsive.
Inspect OSGi services and Sling Models
When a service appears to be unavailable, inspect dependency injection before changing business logic. A Declarative Services component may remain unsatisfied because a referenced service is missing, a configuration PID is incorrect, or a target filter excludes the available implementation. Eclipse can show the Java-side dependency, while the Web Console reveals the runtime component state.
For Sling Models, examine the adaptable object and every injected field. A model adapted from a resource behaves differently from one adapted from a request. Optional injections may quietly produce null values, while required injections can prevent model creation altogether. Step through the model’s initialization method and inspect the resource path, resource type, current page, and request attributes.
Repository content should be inspected at the same time as Java state. CRXDE Lite, repository browser tools, and targeted queries can reveal whether a property is absent, stored under a different node, or authored with an unexpected type. A string that looks correct in a dialog may be stored as a multi-value property, a date, or a referenced asset, changing how the model reads it.
Use logs, exceptions, and request traces together
The Eclipse debugger shows what happens in one execution thread, while AEM logs explain what happens across the wider request lifecycle. Set focused log levels for the relevant package rather than enabling verbose logging globally. Include meaningful identifiers such as the content path, job ID, correlation value, or external request ID in application logs.
Pay attention to the first meaningful exception in a stack trace. Later errors are often consequences of an earlier failure, such as a null service, a repository permission issue, or a failed HTTP response. Eclipse’s Variables and Expressions views help verify assumptions at the exact line where state changes, while the log shows whether the same condition affects other requests.
For asynchronous work, remember that the original HTTP thread may finish before a job, scheduler, workflow step, or event handler runs. Place breakpoints in the consumer code and inspect the event properties or job payload. A request that looks successful in a browser can still produce a failed background operation several seconds later.
Compare debugging approaches in daily AEM work
Different problems call for different levels of inspection. Remote debugging is powerful, but logs, repository queries, and unit tests may provide faster evidence for configuration or content issues. The following comparison helps choose a suitable starting point.
| Technique | Best used for | Main strength | Common limitation |
|---|---|---|---|
| Eclipse remote debugger | Java control flow and state | Inspect variables line by line | Requires matching source and deployed code |
| Package-level logging | Runtime behavior and timing | Works across threads and instances | Excessive logging can obscure the signal |
| OSGi Web Console | Services, bundles, and configurations | Shows live component status | Does not explain every business decision |
| CRXDE Lite or repository tools | Content and property inspection | Reveals actual stored data | Manual checks may not scale |
| Automated tests | Repeatable defects and regressions | Fast, isolated verification | May not reproduce authoring or infrastructure issues |
| Browser and network tools | Client-side rendering and requests | Exposes payloads and response codes | Cannot inspect server-side Java state |
A productive workflow usually combines two or three of these techniques. For example, a component that renders incorrectly may require browser inspection to confirm the request, repository inspection to validate authored values, and Eclipse to check model adaptation. Choosing the narrowest useful tool keeps debugging focused.
AEM teams can also learn from the range of perspectives represented by the event’s conference speakers, including specialists working across architecture, integrations, and application development. Cross-disciplinary knowledge matters because a rendering defect may originate in Java, content structure, caching, or front-end behavior.
Investigate performance and external integrations
Eclipse provides several ways to identify slow Java code. Use timing logs around repository queries, HTTP calls, and resource-intensive transformations before assuming that a particular method is responsible. The debugger’s step operations are excellent for correctness checks, but they alter timing and are unsuitable for measuring production-like performance.
Watch for repeated repository traversal, unbounded result sets, and network calls inside loops. A service that works correctly with a few pages may become slow when a query scans a large subtree or when an external API responds slowly. Capture connection timeouts, response codes, and sanitized request metadata so that integration failures can be reproduced without exposing credentials.
When debugging cloud or shared environments, avoid attaching a debugger to live traffic unless the platform and operational policy explicitly permit it. Prefer local reproduction, lower environments, request correlation, and temporary diagnostic logging. Sensitive content and authentication tokens should never be copied into source code, screenshots, or public issue reports.
Build a repeatable troubleshooting routine
A consistent sequence makes AEM defects easier to explain and fix. Record the environment, run mode, content path, request details, bundle version, and observed error before making changes. Then narrow the issue through a small set of checks:
- Confirm the deployed bundle and source code correspond.
- Reproduce the request with the same selector, extension, and content path.
- Check OSGi component state and configuration values.
- Inspect repository properties and permissions.
- Attach Eclipse only after identifying the most likely execution path.
After the fix, remove temporary breakpoints and verbose loggers, rebuild the project, and repeat the original reproduction steps. Add a unit, integration, or request-level test when the defect exposes a missing safety check. A short record of the cause, evidence, and resolution can save substantial time when a similar issue appears in another environment.
Developers who want to compare debugging habits with recorded technical sessions can browse the session recordings from CIRCUIT. Discussions covering architecture, integrations, analytics, and open-source practices can broaden the investigation beyond a single Java class.
Turn debugging into shared engineering practice
Good debugging becomes more valuable when the team can repeat it. Establish a standard local startup profile, documented debug ports, package-specific logger names, and a clear process for matching deployed artifacts to Git commits. These small conventions reduce confusion during code reviews and handoffs.
Keep environment-specific values outside source code, validate configuration during deployment, and make failures observable without exposing private data. When a defect crosses AEM, a browser, and an external service, invite the relevant specialists early rather than treating each layer as an isolated problem. Teams attending future technical events can also review registration details when planning professional development around AEM and Java.
Use Eclipse as a precise instrument, not as the only source of truth. Pair breakpoints with request analysis, OSGi inspection, repository evidence, logs, and repeatable tests. That combination turns difficult AEM behavior into a traceable sequence of decisions—and gives your team a practical debugging method it can apply to the next release.