Bundle won't start
Purpose: Diagnose bundles stuck in Installed/Resolved and DS components that refuse to activate.
Who this page is for
| Audience | Why it matters to you |
|---|---|
| Backend engineers | The classic deploy-day symptom |
Decision tree
/system/console/bundles → find your bundle
├─ ACTIVE but feature dead → it's not the bundle: DS component issue ↓ or wrong version deployed
├─ INSTALLED → unresolved imports:
│ expand bundle → "Imported Packages" → red entries name the missing package+version
│ ├─ package missing entirely → dependency not deployed/embedded
│ └─ version range unsatisfiable → uses-conflict / AEM provides other version
└─ RESOLVED → resolvable but not started → start it; if it drops back, check error.log for activator/DS failureUnresolved import fixes
| Cause | Fix |
|---|---|
| Third-party lib not OSGi-ready / not present | Embed it: maven-bundle-plugin -includeresource + Import-Package tuning in core/pom |
| Import version range vs AEM's export | Check /system/console/depfinder for what AEM exports; align dependency version or widen range deliberately |
| Optional dependency dragged in | Mark resolution:=optional for genuinely optional imports |
| Split across your bundles after refactor | Deploy order/embed — the all package should carry both |
DS component won't activate (bundle Active)
/system/console/components → find component → state and unsatisfied references listed:
| State says | Meaning |
|---|---|
| unsatisfied (reference) | A @Reference target service is missing — recurse: THAT component's problem first |
| unsatisfied (configuration) | configurationPolicy=REQUIRE and no config exists for the PID — ship the config (run modes) |
| failed activation | Exception in @Activate — error.log has it |
| Not listed at all | Annotation processing failed at build (check the generated XML in the jar) or wrong bundle deployed |
Prevention
Deploy verification in the pipeline asserts zero non-Active bundles + zero unsatisfied components (runbook check) — this page should be a dev-time read, not a prod-incident one.