Liferay Troubleshooting: Common Issues and Fixes | OpsBlu Docs

Liferay Troubleshooting: Common Issues and Fixes

Debug analytics issues on Liferay DXP — theme template injection, Liferay Analytics Cloud conflicts, portlet rendering, and fragment-based tracking...

Liferay DXP (formerly Liferay Portal) is a Java-based enterprise platform with a portal architecture, theme system, and built-in analytics service (Liferay Analytics Cloud). Analytics issues on Liferay typically involve conflicts between the built-in Analytics Cloud and third-party tracking, theme template inheritance, portlet rendering lifecycle, and the fragment/widget system that controls page composition.

Liferay-Specific Debugging Approach

Liferay has its own analytics product (Liferay Analytics Cloud) that auto-injects tracking. Before debugging third-party analytics, determine whether Analytics Cloud is active.

Check Liferay Analytics Cloud Status

// In browser console, check if Liferay Analytics Cloud is injected
console.log('Liferay Analytics:', typeof Analytics !== 'undefined' ? 'Active' : 'Not loaded');
console.log('AC script:', document.querySelector('script[src*="analytics"]')?.src || 'none');

// Check for Liferay's own tracking pixel
const lrTracking = document.querySelector('script[data-analytics-tool="liferay"]');
console.log('LR Analytics tool:', lrTracking ? 'present' : 'not found');

Verify Theme Template Output

# Check the rendered page for analytics tags
curl -s -L "http://your-liferay-site.com/" | grep -iE "gtag|gtm|analytics" | head -10

# Check Liferay server logs for template errors
tail -100 /opt/liferay/logs/liferay.log | grep -i "theme\|template\|freemarker\|error"

Check via Liferay's Gogo Shell

# Access the Gogo shell (Liferay 7.x/DXP)
telnet localhost 11311

# Check active bundles related to analytics
lb | grep -i analytics

# Check if custom theme is deployed
lb | grep -i theme

Most Common Liferay Analytics Issues

1. Liferay Analytics Cloud Conflicting with GA/GTM

Symptoms: Double tracking, inflated pageviews, or JavaScript errors from competing analytics scripts.

Root cause: Liferay Analytics Cloud is enabled at Control Panel > Instance Settings > Analytics Cloud and auto-injects its own tracking. If you also add GA or GTM, both fire simultaneously.

Fix: Either disable Analytics Cloud or remove your manual tracking:

# To disable Liferay Analytics Cloud:
# Control Panel > Instance Settings > Analytics Cloud > set Token to empty
# Or via portal-ext.properties:
analytics.cloud.enabled=false

2. FreeMarker Theme Template Not Rendering Scripts

Symptoms: Analytics code added to the theme but not appearing in the page output.

Root cause: Liferay 7.x/DXP uses FreeMarker templates in themes. If your analytics code is in the wrong template file or a FreeMarker syntax error prevents rendering, the scripts silently fail.

Fix: Place analytics in the theme's portal_normal.ftl:

<#-- In your theme's src/templates/portal_normal.ftl -->
<head>
  <title>${htmlUtil.escape(the_title)}</title>
  ${theme.include(themeDisplay, "head_top_include")}

  <#-- Analytics code goes here -->
  <script async src="https://www.googletagmanager.com/gtag/js?id=G-XXXXXXX"></script>
  <script>
  window.dataLayer = window.dataLayer || [];
  function gtag(){dataLayer.push(arguments);}
  gtag('js', new Date());
  gtag('config', 'G-XXXXXXX');
  </script>

  ${theme.include(themeDisplay, "head_bottom_include")}
</head>

3. Fragment-Based Pages Missing Tracking

Symptoms: Content pages built with fragments track correctly, but some fragment compositions are missing analytics.

Root cause: Liferay's Page Builder uses fragments. If you create a master page template with analytics in it, pages using that master will have tracking. Pages using a different master or no master may not.

Fix: Add analytics to all master page templates, or use the theme-level injection which applies regardless of master page:

# Via Control Panel > Site Settings > Pages > Custom Script
# Add your analytics snippet to the "JavaScript" field
# This applies to all pages in the site regardless of master template

4. Portlet Rendering Lifecycle Causing Timing Issues

Symptoms: Analytics loads but custom events do not fire on portlet interactions. Portlet content appears after analytics initialization.

Root cause: Liferay portlets render asynchronously. The portlet lifecycle may complete after the analytics initialization, meaning event listeners set up during page load miss portlet-generated content.

Fix: Use event delegation or wait for Liferay's portlet lifecycle:

// Wait for all portlets to render before setting up event tracking
Liferay.on('allPortletsReady', function() {
  // Now safe to set up event tracking on portlet content
  document.querySelectorAll('[data-track-click]').forEach(el => {
    el.addEventListener('click', function() {
      gtag('event', 'portlet_interaction', {
        portlet_id: this.closest('[data-portlet-id]')?.dataset.portletId
      });
    });
  });
});

5. Virtual Instance / Multi-Site Tracking Separation

Symptoms: Analytics data from different virtual instances or sites within Liferay is mixed together.

Root cause: Liferay supports virtual instances (separate sites on the same installation). Each virtual instance needs its own analytics configuration.

Fix: Configure analytics per virtual instance:

# In Control Panel > Virtual Instances > [your instance] > Settings
# Or in portal-ext.properties with company ID prefix:
company.123456.analytics.tracking.id=G-XXXXXXX

Environment Considerations

  • Liferay CE vs DXP: DXP (commercial) includes Analytics Cloud and additional features. CE (community) does not include Analytics Cloud
  • OSGi architecture: Liferay 7.x/DXP uses OSGi bundles. Custom modules for analytics must be proper OSGi bundles deployed through the deploy folder or Gogo shell
  • Theme deployment: Themes are deployed as WAR files or Liferay Theme Generator projects. After theme changes, redeploy the theme and clear the cache
  • Docker support: Liferay provides official Docker images. Container-based deployments may need volume mounts for theme customizations
  • Clustering: Enterprise Liferay deployments often run in clusters. Ensure analytics configuration is consistent across all cluster nodes

Performance Issues

  • LCP Issues - Portlet rendering pipeline latency and theme resource loading
  • CLS Issues - Layout shifts from async portlet rendering and fragment composition

Tracking Issues

  • Events Not Firing - Debug Analytics Cloud conflicts, theme template rendering, and portlet lifecycle timing
शीर्ष पर वापस जाएँ