All posts
OSGi · 11 min read · Feb 26, 2026

Why Liferay Components Can Be Satisfied but Not Active

OSGi declarative services component lifecycle states

The scene is familiar. You deploy a module, the bundle starts cleanly, no exception appears in the log, and yet the feature does nothing. You open the Gogo shell, list your components, and find the one you care about sitting in state Satisfied rather than Active. Most developers read that as failure and start rewriting code. In practice, roughly half the time nothing is wrong at all - Satisfied is simply where that component is supposed to rest.

Getting this right requires separating two things that are easy to conflate: the bundle lifecycle, which decides whether your code can run, and the component lifecycle, which decides whether an instance of your class exists right now. The OSGi runtime itself manages the first. Declarative Services manages the second, and it has its own rules.

The states a component actually moves through

Declarative Services tracks each component through a small state machine. The names vary slightly between tools, but the meaning is consistent:

  • Unsatisfied reference: at least one mandatory reference has no matching service in the registry.
  • Unsatisfied configuration: the component demands configuration that Configuration Admin does not have.
  • Satisfied: every dependency is met. The component is eligible to run, and its service - if it declares one - is already visible in the service registry.
  • Active: an instance exists, the activate method has completed, and the object is live in memory.

The important and counter-intuitive part is the gap between the last two. Satisfied does not mean waiting for something. It means ready, and possibly deliberately not instantiated yet.

Satisfied means eligible, not running

Declarative Services distinguishes between delayed components and immediate components. A component that provides a service is delayed by default. When it becomes satisfied, the runtime registers the service in the registry immediately but does not construct your object. Construction is deferred until the first consumer actually asks the registry for that service. Only then does the component become Active.

java
// Delayed by default: the service is registered when satisfied,
// but the instance is created on first use. Resting state = Satisfied.
@Component(service = InvoiceValidator.class)
public class InvoiceValidatorImpl implements InvoiceValidator { }

// Immediate: the runtime constructs the instance as soon as it is
// satisfied. Resting state = Active.
@Component(immediate = true, service = InvoiceValidator.class)
public class EagerInvoiceValidatorImpl implements InvoiceValidator { }
Whether Satisfied or Active is the correct resting state depends on how the component is declared.

This is why a perfectly healthy service component can sit in Satisfied indefinitely: nothing has asked for it yet. A validator that only runs during a nightly job will be Satisfied for twenty-three hours a day and Active for one. That is the design working, not failing.

When Satisfied is the wrong resting state

The rule flips for components that do not provide a service. A component with no service interface has nothing for anyone to look up, so the runtime treats it as immediate: if it is satisfied, it should also be active. This covers a large share of what Liferay developers write - portlets, servlet filters, scheduled jobs, model listeners, and lifecycle actions all take effect by being constructed.

Component shapeExpected resting stateSatisfied but not Active means
Provides a service, immediate not setSatisfiedNormal - no consumer has requested it yet
Provides a service, immediate = trueActiveSomething failed during activation
Provides no serviceActiveSomething failed during activation
Factory componentOne instance per configurationNo configuration has been created yet
Read the state against the component's declaration, never in isolation.

So the first diagnostic question is not why is this Satisfied. It is what should this component's resting state be, given how I declared it. If the answer is Satisfied, stop looking. If the answer is Active, you have a real problem, and it is almost always one of the three below.

Cause one: a reference that can never be satisfied

A mandatory reference blocks activation until a matching service appears. The subtlety is that matching is not only about the interface - a target filter narrows it further, and a filter that matches nothing is indistinguishable from a service that was never registered.

java
@Reference(target = "(model.class.name=com.example.Invoice)")
private ModelListener<Invoice> _modelListener;

// The component stays unsatisfied unless some other component
// registers a ModelListener AND publishes that exact property.
// A typo in the property name looks identical to a missing service.
Target filters are the most common reason a reference never binds.

Cardinality matters just as much. A reference is mandatory by default, so declaring an optional collaborator without marking it optional turns a nice-to-have into a hard blocker. If the collaborator really is optional, say so explicitly and handle the absent case in code rather than letting the whole component refuse to start - a distinction that gets more consequential as the service graph grows.

Cause two: configuration the runtime does not have

A component can declare that configuration is required rather than optional. When it does, Configuration Admin must hold a matching configuration before the component is eligible at all. Without one, the component is not satisfied - it is unsatisfied on configuration, which is a different problem with a different fix.

Factory components take this further. They produce one instance per configuration, which means zero configurations produce zero instances. Nothing is broken, nothing is unsatisfied, and nothing appears in the log. The component simply has no reason to exist yet. In Liferay this usually resolves to a missing entry in System Settings or a missing config file in the osgi/configs folder.

Cause three: activation that fails quietly

If the activate method throws, the instance is discarded. The runtime logs the failure, but the component falls back to Satisfied rather than staying Active - and for a delayed component it will try again the next time someone requests the service. The result is a component that looks merely idle while it is actually failing on every single attempt.

java
@Activate
protected void activate(Map<String, Object> properties) {
    // A missing property, an unreachable endpoint, or an invalid
    // config value thrown from here leaves the component Satisfied,
    // not Active - and the only evidence is in the log.
    _endpoint = GetterUtil.getString(properties.get("endpoint"));

    if (Validator.isNull(_endpoint)) {
        throw new IllegalStateException("endpoint is required");
    }
}
An exception in activate produces a silent state change, not a loud failure.

This is the strongest argument for keeping activation cheap. Work that can fail - opening connections, reading remote configuration, warming caches - is better done lazily on first use, where the failure surfaces as a real exception to a real caller instead of disappearing into a state transition.

The chain effect

Components depend on components. When a low-level service fails to activate, every component referencing it becomes unsatisfied, and every component referencing those becomes unsatisfied in turn. What you notice first is usually the top of the chain - the portlet that will not render - while the actual defect sits several levels down in something you did not touch today.

The practical consequence is that you should never fix the component you noticed first. Follow the unsatisfied reference down until you reach a component whose own references are all bound. That one is the root cause, and fixing it usually clears the entire chain at once.

Reading the signal correctly

What you observeMost likely meaningWhere to look next
Component not listed at allThe component descriptor was never generatedThe build output and bundle metadata
Unsatisfied referenceNo service matches the interface plus target filterThe provider component, one level down
Unsatisfied configurationRequired configuration is absentSystem Settings and osgi/configs
Satisfied, service declaredUsually healthy - nobody has consumed itNothing, unless a consumer is also broken
Satisfied, no service declaredActivation is failingThe log, for an exception thrown during activate

Conclusion

Satisfied but not Active is not an error code. It is a statement about eligibility, and its meaning depends entirely on how the component was declared. A delayed service component resting in Satisfied is the runtime doing exactly what it promised. An immediate component stuck in Satisfied is a failure hiding behind a state name. Once you learn to ask what the resting state should be before asking what went wrong, this stops being mysterious - and the step-by-step debugging path becomes a short, repeatable routine instead of an afternoon of guesswork.

Contact

Let’s connect

Have a Liferay or Backend project you’d like to talk through? Fill in the form and I’ll get back to you.

Book Calendar