Debugging AEM SDK using the OSGi web console

The AEM SDK’s local quickstart has an OSGi web console that provides a variety of information and introspections into the local AEM runtime that are useful to understand how your application is recognized by, and functions within AEM.

AEM provides many OSGi consoles, each providing key insights into different aspects of AEM, however the following are typically the most useful in debugging your application.


The bundles console lists all the OSGi bundles deployed AEM. Each one represents a bundle, listing the name, version status and actions, including the ability to start and stop. The status is of particular interest as it denotes if the bundle was able to start or not. Active means the bundle started and is ready to go. Resolve means the bundle was stopped. And most interestingly, is the installed state. This indicates that the bundle is installed but not active. Most of the time, this actually means something is preventing the bundle from becoming active, which is usually a problem. And we’ll dig into this in a minute. Clicking into a bundle, we see its details. Exported packages, list the Java packages this bundle exports, or in other words makes available to the rest of AEM, including HTL scripts. Imported packages, lists the Java packages from which this bundle imports classes from other bundles in AEM. Not only does it list the Java packages but also the version or version ranges it requires for those packages, as well as which bundles it’s importing it from.
Let’s jump over to another bundle to see how this can be useful. Here’s an installed bundle. And when we click the enable button, here it means installed rather than turning active. Clicking into it, we see why. It has an unresolved import dependency that’s preventing it from starting up. To remedy this, we’d want to make sure we’re compiling our code against the latest AEM-API Maven dependency. As well as ensure we aren’t introducing any other custom Maven dependencies into our projects POM files that might be resulting in this unsatisfied import requirement. Okay, let’s take a look at one more OSGi bundle to see some of the extra detail it can provide. Bundle details lists all OSGi services it exposes along with their service interface and implementing Java classes.
Then comes the OSGi manifest headers, which are the system level description of what’s in the bundle.
Followed by the OSGi components declared in the bundle along with if they’re enabled or disabled.
And lastly, any OSGi services this bundle uses. So, as you can see, the bundles console is a powerful tool when it comes to understanding how your OSGi bundle is behaving in the AEM runtime. Note that the information found here is available for AEM as a Cloud Service environments via the cloud-based dev console. However, this exact console is only available on the local AEM runtime. -

The Bundles console is a catalog of the OSGi bundles, and their details, deployed to AEM, along with the ad hoc ability to start and stop them.

The Bundles console is located at:

Clicking into each bundle, provides details that help with the debugging your application.

  • Validating the OSGi bundle is present
  • Validating if an OSGi bundle is active
  • Determining if an OSGi bundle has unsatisfied imports preventing it from starting


The components console lists all the OSGi components in AEM. Each row represents an OSGi component listing the name, status along with the ability to start, stop or configure. The status is of particular interest as it denotes if the OSGi component is active or not. A status of active means the OSGi components started and everything’s good. Satisfied means it can become active. However, nothing else in AEM has used it yet. So it’s sitting there waiting to become active. No config means it requires an OSGi configuration to be present to become active, but no configuration is present. Therefore it can’t become active. This is typically set via the configuration policy required flag, in the Java reference annotation. Unsatisfied means the OSGi component cannot become active because it depends on some other OSGi service reference that cannot be satisfied. Usually, this means the reference service doesn’t exist or that the reference OSGi service itself is unsatisfied.
And disable means that the OSGi component has been explicitly made unavailable. Clicking into a component reveals these details. There’s all sorts of helpful things to look at here. Default state activation and configuration policy all provide insights into when this OSGi component should become active. Services lists all the Java interfaces, this component exposes itself as an OSGi service. So if you want to leverage this OSGi component in your code, you need to make a reference to the OSGi service interface listed here. The PID is what’s used as the file name of the OSGi configuration file used to configure this OSGi component. References lists all the OSGi service references this component has, and how those references are defined. If a references are acquired, but unsatisfied, it’ll show up here, and helps you track down why an OSGi component might have the unsatisfied status. And lastly, the properties. These are all the OSGi configuration properties that are bound to, and in use by the OSGi component. This not only provides you with the details of what OSGi configuration state is in use by the OSGi component, but it also provides a nice view of what the OSGi configuration property names are for a particular OSGi component. If you’re trying to declare your own OSGi configuration file for it. So as you can see, the components console provides a number of helpful insights into the OSGi components in AEM. Remember that if none of your OSGi bundles or share components are listed here, it typically means that your OSGi bundle wasn’t installed or was unable to become active for some reason. Note that the information found in this console is available for AEM as a cloud service environment via the cloud-based dev console. However, it’s this exact console is only available for the local AEM runtime. -

The Components console is a catalog of all the OSGi components deployed to AEM, and provides a all information about them, from their defined OSGi component life cycle, to what OSGi services they may reference to

The Components console is located at:

Key aspects that help with the debugging activities:

  • Validating the OSGi bundle is present
  • Validating if an OSGi bundle is active
  • Determining if an OSGi bundle has unsatisfied imports preventing it from starting
  • Obtaining the component’s PID, in order create OSGi configurations for them in Git
  • Identifying OSGi property values bound to the active OSGi configuration

Sling Models

The Sling Models Console displays a variety of information about sling models. The first few sections list the various implementations for different aspects of the sling model engine. These are typically provided by either sling or AEM. However, in more complex applications, custom implementations may be provided as well. If you have any, this console can help you understand if your customer implementations have been registered by the sling engine for use. The sections that fall into this classification are Injectors, Inject Annotation Processor Factories, Implementation Pickers, and Via Providers.
The last few sections are more interesting for debugging your application as they list what sling models are registered in AEM and how they’re registered. If your sling model isn’t listed in one of these sections, it typically means either your OCI bundle isn’t started. Sling model annotations on the Java classes are incorrect or that your core projects Palm is not configured to identify which Java classes are sling model. The sections are broken up by what the sling model is adaptable from a resource or request, and if they have a resource type they’re registered with. This information can be helpful to understand why adapting to or using the model factory to obtain a sling model may return null or the incorrect model type. Note this does not show what Java interfaces sling models may be bound to and requested through. Simply which model implementation clashes are recognized and registered.
Lastly, Sling Model Exporter Servlets, list all the sling models that have been annotated to act as sling model exporters. This is often most helpful for debugging issues with spot editor or AEM content services. Which heavily use the Jackson serialization of sling models to generate their Jason.
If a component is not rendering as Jason and the model of that Jason output, you can check this list to ensure the model is in fact registered to the correct resource type as an exporter and that it is bound to the model selector. -

The Sling Models console is located at:

Key aspects that help with the debugging activities:

  • Validating Sling Models are registered to the proper resource type
  • Validating Sling Models are adaptable from the correct objects (Resource or SlingHttpRequestServlet)
  • Validating Sling Model Exporters are properly registered