This section covers common issues and solutions for analytics and tracking on Adobe Experience Manager (AEM).
Common Issue Categories
Performance Issues
- LCP (Largest Contentful Paint) - Slow page load issues
- CLS (Cumulative Layout Shift) - Layout stability problems
Tracking Issues
- Events Not Firing - Missing or incomplete tracking
AEM-Specific Considerations
Author vs Publish
Tracking should behave differently in each mode:
| Mode | Tracking | Purpose |
|---|---|---|
| Author (EDIT) | Disabled | Content editing |
| Preview | Optional | Content preview |
| Publish (DISABLED) | Enabled | Production |
Check WCMMode in your models:
import com.day.cq.wcm.api.WCMMode;
public boolean shouldTrack() {
WCMMode mode = WCMMode.fromRequest(request);
return mode == WCMMode.DISABLED;
}
Dispatcher Caching
Dispatcher can affect tracking:
| Issue | Cause | Solution |
|---|---|---|
| Stale data layer | Cached HTML | Use client-side API calls |
| Missing cookies | Cache includes cookies | Configure Dispatcher rules |
| CSP blocking | Cached headers | Update CSP configuration |
Sling Model Lifecycle
Models are request-scoped by default:
@Model(adaptables = SlingHttpServletRequest.class,
cache = true) // Cache within request
public class TrackingModel {
// ...
}
Quick Diagnostic Checklist
Tracking Not Working
- Check WCMMode (should be DISABLED on Publish)
- Verify OSGi configuration is active
- Check browser console for JS errors
- Confirm GTM/GA scripts loading in Network tab
- Validate dataLayer in console
- Check Dispatcher cache headers
Performance Issues
- Check clientlib loading order
- Verify async/defer on scripts
- Review Core Web Vitals
- Check for render-blocking resources
Debugging Tools
AEM Developer Tools
- OSGi Console: /system/console/configMgr
- Sling Log: /system/console/slinglog
- Query Debug: /libs/granite/operations/content/diagnosis/tool.html
Enable Debug Logging
In OSGi Console, set log level:
com.mysite.core.models=DEBUG
Common Error Messages
| Error | Cause | Solution |
|---|---|---|
dataLayer is undefined |
Script order issue | Initialize dataLayer before GTM |
gtag is not defined |
GA not loaded | Check script inclusion |
Model not found |
Missing annotation | Add @Model annotation |
Service unavailable |
OSGi not activated | Check component activation |
Support Resources
- AEM Documentation
- AEM Core Components
- Global Issues Hub - Platform-agnostic troubleshooting