Build & deploy failures
Purpose: Fix the recurring Maven build and package-installation failures in AEM projects.
Who this page is for
| Audience | Why it matters to you |
|---|---|
| All engineers | Everyone builds and deploys |
Build-time (mvn) classics
| Failure | Cause → fix |
|---|---|
| filevault-package validation errors | Malformed .content.xml (unclosed tag, undeclared namespace) — the message names the file; XML in ui.apps is code, lint it |
| "Package … not found" imports at bundle build | Dependency scope/version — align with AEM's provided deps (uber-jar/api jar per your setup) |
| Frontend build fails in ui.frontend | Node/npm version drift — pin via frontend-maven-plugin so CI and laptops agree |
| Tests fail only in CI | Timezone/locale/fixture-path assumptions in AEM mocks tests |
| SNAPSHOT resolution failures | Someone released with SNAPSHOT deps (versioning rules) |
Install-time classics (package installs but wrongness follows)
| Symptom | Cause |
|---|---|
| Content vanished after deploy | Filter mode replace over an authored path — the filter discipline table exists because of this exact grief; restore from the pre-install snapshot packmgr kept, then fix filter.xml |
| Old code still running after install | Bundle didn't refresh (same version number re-deployed — SNAPSHOT locally is fine, versions must bump for releases), or install left the bundle not Active |
| Works locally, fails on instance | Run-mode config missing for that environment (config management); or local had manual CRXDE edits never committed — the drift lesson |
| Install hangs / instance sick after | Huge package (binaries in ui.apps?), or install triggered mass reindex (index changes note) |
| "Constraint violation" on install | Package assumes a node structure/namespace the target lacks — dependency package order in the all embed list |
The golden debugging shortcut
Unzip the actual artefact and LOOK: jcr_root/… contains what will land, filter.xml says what will be owned. Half of "the deploy did something weird" is resolved by reading the zip instead of theorising about the build (packages page).
Prevention
Pipeline gates: validator on packages, zero-tolerance bundle status check post-install, canary smoke (pipeline) — every classic above has a cheap automated detector.