Debugging Liferay OSGi Components: From Satisfied to Active
Knowing what the component states mean tells you whether you have a problem. This post is about what to do once you know you do. The single biggest improvement most teams can make is to stop debugging in the order the symptoms appear and start debugging in a fixed order, from the outside in.
Work from the outside in
Every failure of the form my module does nothing sits at exactly one of six layers. Checking them in order matters, because a failure at any layer makes every layer above it look broken too.
- Is the artifact physically deployed where the portal is watching?
- Is the bundle installed and resolved, or stuck unresolved?
- Did the component get registered with Declarative Services at all?
- Are all mandatory references bound?
- Is the required configuration present?
- Did activation complete without throwing?
Skipping straight to the last step is the standard mistake. If the answer is at step three, nothing you learn at step six will be true.
Steps 1 and 2: the bundle
Start in the Gogo shell and confirm the bundle exists and resolved. An Installed state means the bundle is present but its imports could not be wired; an Active state means its code is available to the runtime. A bundle that never leaves Installed will never register a single component, no matter how correct your annotations are.
| Command | What it answers |
|---|---|
| lb <text> | Is the bundle installed, and what state is it in? |
| diag <bundleId> | Why did this bundle fail to resolve? |
| headers <bundleId> | What does it actually import and export? |
| scr:list <bundleId> | Which components were found in this bundle? |
| scr:info <componentName> | Full state, references and configuration for one component |
| services <filter> | Which services are registered right now, and by whom? |
When diag reports a missing import, the fix is nearly always in the build rather than the code: a package that is used but not imported, a version range that no longer matches, or a dependency bundled privately in one module and exported from another.
Step 3: did the component register at all
This step catches the failure that wastes the most time, because it produces no error anywhere. List the components for your bundle and look for your class. If the class is not listed, Declarative Services never saw it - which means the component descriptor was not generated at build time, and the problem is in your build, not your runtime.
- The annotations came from the wrong package, so the build tool ignored them.
- The annotations sit on a superclass, and the build was not told to inherit them.
- The class was compiled but excluded from the bundle, or landed on the classpath rather than inside it.
- An older copy of the same bundle is still installed and winning.
The last one deserves emphasis. Two versions of the same bundle can coexist, and the runtime may be happily serving the old one while you edit the new one. Listing bundles by name rather than by id makes duplicates obvious immediately.
Step 4: read the component detail properly
Once the component is listed, the component detail command is the highest-value step in the whole exercise. It prints the state and, crucially, every reference with its own satisfied or unsatisfied marker.
Component Description: com.example.invoice.InvoiceExportPortlet
State: unsatisfied reference
Config PID: com.example.invoice.InvoiceExportPortlet
Configuration Policy: optional
References:
_invoiceService interface: com.example.invoice.InvoiceService
cardinality: 1..1 policy: static
target: (model.type=export)
STATE: unsatisfied
_userLocalService interface: com.liferay.portal.kernel.service.UserLocalService
cardinality: 1..1 policy: static
STATE: satisfiedThree things in that output tell you where to go next: which reference is unsatisfied, what interface it wants, and what target filter it applies. Here the interface exists in the system - the filter is what fails. That is a very different fix from a service that was never registered.
Step 5: follow the reference down
Take the interface from the unsatisfied reference and ask the registry whether anything provides it. If nothing does, the provider component is your new subject: go back to step three with that component and repeat. If something does provide it, compare the properties it publishes against the target filter character by character.
// The consumer expects this property ...
@Reference(target = "(model.type=export)")
private InvoiceService _invoiceService;
// ... but the provider publishes a differently named one.
@Component(
property = "model.kind=export",
service = InvoiceService.class
)
public class ExportInvoiceServiceImpl implements InvoiceService { }This recursion is the core of the technique. You are walking down a dependency chain until you reach a component whose references are all satisfied. That component is the root cause. Everything above it is a symptom, and fixing it clears the whole chain in one deploy.
Step 6: configuration and the log
If the state mentions configuration rather than references, the registry is not the problem. Check whether a matching configuration exists in System Settings, and whether a config file for that PID is present and syntactically valid in the osgi/configs folder. A malformed config file is a particularly nasty case: the file exists, so it looks configured, but Configuration Admin rejected it and the component behaves exactly as if you had never written it.
Finally, the log. Raising the log level for the Declarative Services runtime turns the whole lifecycle into a visible narrative - components being enabled, references binding and unbinding, activation succeeding or throwing. Combined with the ordered checks above, this is usually where a silent activation failure finally announces itself.
The mistakes behind most of these
- A mandatory reference on a collaborator that is genuinely optional, turning a degraded feature into a dead component.
- Target filters written against properties the provider never publishes, or publishes with different spelling.
- Referencing a concrete implementation class that was never registered under that type as a service.
- Heavy or failure-prone work inside activate, where the failure disappears into a state change.
- A configuration PID that does not match the file name in osgi/configs.
- immediate = true added reflexively, which converts a harmless idle state into a genuine startup dependency.
- Circular references between two components, where neither can ever satisfy the other.
- Stale bundles from a previous deploy still resolving ahead of the new one.
Make the next one easier
Debugging speed is mostly a property of how the module was written. A few habits pay for themselves repeatedly: validate configuration during activation and fail with a message that names the missing key, keep mandatory references to the things you genuinely cannot run without, prefer filters on stable published properties over clever ones, and log a single line on successful activation so its absence is itself a signal.
It is also worth remembering that every mandatory reference you add is a new way for the component to be blocked at startup. That is a design choice with the same character as any other coupling decision in a portal: cheap to add, quietly expensive to live with.
Conclusion
There is no intuition required here, only order. Confirm the bundle resolved, confirm the component registered, read the reference detail, follow the unsatisfied reference down to its root, then check configuration and the log. Done in that sequence, the question stops being why is my module broken and becomes which of six specific layers failed - and that question always has an answer you can find in a few commands.