CIRCUIT

Using Apache Felix Console to Inspect OSGi Bundles in AEM

Adobe Experience Manager is built on OSGi, a modular Java framework that loads applications as bundles and manages their relationships at runtime. When an AEM component fails to render, a servlet is ignored, or a service appears unavailable, the Apache Felix Web Console provides a practical view of what is happening beneath the authoring interface. Learn more about How To Create A Strong Online Presence Before And After The Festival.

For Australian development teams, this is especially useful when an AEM environment spans local Docker containers, an enterprise data centre, and cloud services in Sydney or Melbourne. The console can reveal whether a deployment problem is caused by a missing package, an unresolved import, an inactive bundle, or a configuration issue before the team spends an entire arvo searching through unrelated logs.

Reaching the Felix Web Console Safely

In a local or author instance, open the Felix console at:

http://localhost:4502/system/console

Use port 4503 for a typical publish instance. AEM Cloud Service does not provide the same unrestricted administrative console in production, so these techniques are mainly applicable to AEM 6.x SDKs, local development environments, and suitably controlled on-premises or managed installations.

Authenticate with an administrator account, preferably through a non-production environment. Never expose /system/console to the public internet. A reverse proxy rule, firewall policy, or incorrect dispatcher configuration can make administrative endpoints reachable from outside the organisation. That is a serious risk for any business, whether the environment supports a Brisbane council website, a Melbourne retailer, or a national financial-services platform subject to strict audit requirements.

The console is made up of several views, including Bundles, Components, Services, Configuration, Packages, and Logs. These screens are closely related. A bundle may be active while one of its Declarative Services components is unsatisfied, or a component may be correctly registered while a request still fails because the relevant servlet mapping is wrong.

Reading Bundle States and Metadata

Select Bundles from the Felix navigation menu to see every installed OSGi module. The list normally includes Adobe product bundles, third-party libraries, project code, and framework services. Useful columns include symbolic name, version, state, and start level.

The most important states are:

  • Active: the bundle has started successfully.
  • Resolved: dependencies are available, but the bundle has not started.
  • Installed: the framework has installed the bundle, but one or more requirements remain unresolved.
  • Starting or Stopping: the lifecycle transition is still in progress.
  • Failure: activation did not complete successfully.

Click a bundle to inspect its manifest and lifecycle details. The symbolic name identifies the module internally, while the version helps establish whether the deployed artifact is the expected build. The Exported Packages and Imported Packages sections show the Java packages exposed by the bundle and those it expects from another module.

A common deployment mistake is importing a package version that is outside the range supplied by the installed dependency. The console may display a message such as uses constraint violation or identify an unresolved package. That evidence is more valuable than simply restarting AEM. Compare the imported version range with the exporting bundle, then check whether the build pulled in an incompatible dependency through Maven.

For broader release context, the ICF Olson profile provides a useful reminder that conference material often sits alongside real implementation experience. Treat the console as an engineering diagnostic tool, not as a substitute for understanding the architecture behind the bundle.

Investigating Dependencies and Services

When a bundle is shown as installed or unresolved, open its detail page and examine the Imported Packages, Required Bundles, and Missing Requirements areas. These entries tell you what the OSGi resolver could not satisfy. The cause might be a missing Adobe API, an incorrect package export, or a version conflict introduced by a custom library.

The Components and Services views add another layer. AEM code commonly uses OSGi Declarative Services, where a component becomes active only when all mandatory references are available. A component marked unsatisfied can point to a missing service, an incorrect configuration PID, or a reference filter that matches nothing.

Suppose a custom workflow step does not appear in the workflow model editor. First, confirm that its implementation bundle is active. Then find the component by its name or Java class and inspect its references. A missing ResourceResolverFactory, incorrect service user mapping, or disabled configuration can prevent activation even when the containing bundle looks healthy.

This is where a live status view resembles a match scoreboard: the visible result is useful, but the individual legs explain why the result occurred. Check the component details, service registrations, and log entries together instead of acting on the top-level bundle colour alone.

Checking Configuration, Packages, and Logs

The Configuration page displays OSGi configuration objects and their PIDs. For a custom service, verify that the expected PID exists and that its values are appropriate for the current run mode. A service may start in a developer environment but remain inactive in production because a required endpoint, credential, or path was configured only in a local .cfg.json file.

Review run-mode folders carefully, especially when using config.author, config.publish, or environment-specific settings. Australian organisations often separate authoring and publishing across regions or availability zones, and a configuration that works in Sydney may expose a stale endpoint or unsuitable timeout when replicated to another environment. Keep secrets out of source control and use the platform’s approved secret-management process.

The Packages view helps identify installed content packages and their relationships. If a deployment updated Java code but not the corresponding /apps or /conf content, the OSGi bundle can be active while the rendered component remains broken. Check package installation order, filters, embedded bundles, and any overlapping paths.

For asset-heavy implementations, inspect the integration boundary as well. A useful reference on AEM and Amazon S3 can help frame questions about external storage, delivery paths, and the difference between an OSGi service being active and the remote storage operation actually succeeding.

Building a Repeatable Troubleshooting Workflow

Start with the symptom and record the exact time, instance, request path, and author or publish role. Then check the error log before changing anything. In the Felix console, open Logs or use the server log files to correlate the request with bundle activation, component registration, repository access, and authentication events.

Next, inspect the suspected bundle without immediately pressing Start, Stop, or Refresh Packages. Manual lifecycle changes can hide the original sequence of events and may create a temporary state that disappears after a restart. If a refresh is necessary in a development environment, capture the bundle state and relevant log lines first.

Use a simple sequence:

  • Confirm the correct AEM instance and run mode.
  • Check the bundle state and version.
  • Read unresolved package and requirement messages.
  • Inspect Declarative Services components and mandatory references.
  • Verify OSGi configuration and service-user permissions.
  • Test the affected request or feature again.
  • Record the root cause and deployment change.

For teams working across Perth, Adelaide, and the eastern states, include the timezone in incident notes. AEST, AEDT, and UTC timestamps can otherwise make a deployment appear to have happened before the failure when logs are being compared across systems. Also account for network behaviour: an NBN-connected developer machine, a corporate proxy, and a cloud-hosted AEM instance may produce different symptoms for the same integration.

Use the console as a controlled diagnostic window, then make durable fixes in code, configuration, or deployment automation. A restart can confirm that a correction is persistent, but it should not be the correction itself. The CIRCUIT FAQ offers additional event context for readers tracing the wider AEM and developer-conference material around these practices.

A well-maintained AEM project should document bundle symbolic names, expected versions, service PIDs, run-mode configuration, and known package dependencies. Pair those records with automated build checks and deployment logs. When a problem reaches production, the team can move from symptom to evidence quickly rather than relying on guesswork or folklore.

Open the Felix console in a safe AEM development instance, choose one custom bundle, and trace its state, imports, components, services, configuration, and logs from start to finish. Record what you find in the project runbook, then apply the same workflow to the next deployment so bundle inspection becomes a normal engineering practice rather than an emergency ritual.