Troubleshooting Guide

Intermediate https://datalayer-tracker.com/knowledge-base/troubleshooting-guide/

Last updated: October 23, 2025 Advanced Topics Custom Events Event Queue System Troubleshooting

Version: 1.0
Last Updated: January 2025
Purpose: Resolve common issues and get your tracking working perfectly

Quick Diagnostics

Before diving into specific issues, run these quick checks to identify the problem:

1. Verify Plugin is Active

Navigate to WordPress Admin → Plugins and ensure Advanced DataLayer Tracker shows as “Active”.

2. Check Browser Console

Open your browser’s developer tools (F12) and look for:

Red error messages
Messages starting with [ADT]
Any JavaScript errors

3. Verify DataLayer

Open browser console and type:

window.dataLayer

You should see an array of events. If you see “undefined”, the dataLayer isn’t loading.

4. Check GTM Container

Ensure your Google Tag Manager container is:

Published (not just saved)
Using the correct Container ID
Imported from the latest ADT export

Events Not Firing

Issue: No Events Appearing in GTM Preview

Possible Causes & Solutions:

1. Feature Not Enabled

Go to WordPress Admin → ADT Settings
Navigate to the relevant tab (Engagement, Forms, Ecommerce, etc.)
Ensure the specific feature is checked/enabled
Click Save Changes

2. GTM Container Not Published

Log into Google Tag Manager
Check if you have unpublished changes
Click Submit to publish your container
Verify container ID matches your site

3. Consent Blocking Events If you’re using a consent management platform:

Open your site and accept all cookies
Check if events now appear
Verify consent status in browser console: window.dataLayerBlocked
If true, consent is blocking events (this is correct behavior until user accepts)

4. Plugin Conflict

Temporarily disable other plugins
Test if events fire
Re-enable plugins one by one to identify the conflict
Contact support with the conflicting plugin name

Issue: Some Events Fire, Others Don’t

Check Event-Specific Requirements:

Form Events require:

Forms to be present on the page
User interaction (forms won’t fire on page load)
Form tracking enabled in settings

Video Events require:

HTML5 <video> elements on page
User to interact with video (play, pause, etc.)
Video tracking enabled in settings

Ecommerce Events require:

WooCommerce installed and active
Products/cart/checkout pages
Ecommerce tracking enabled in settings

Session Summaries require:

Premium license active
User to navigate away or close tab
Session Manager enabled in settings

GTM Container Issues

Issue: Container Import Fails

Error: “Container format not supported”

Solution:

Ensure you’re using the latest version of Advanced DataLayer Tracker
Go to ADT Settings → GTM Export
Click Export Container JSON again
Try importing the new file
If issue persists, contact support with your WordPress and GTM versions

Error: “Duplicate names found”

Solution:

During import, choose Merge option (not Overwrite)
Or create a new workspace in GTM for a clean import
After successful import, review and remove any duplicate tags

Issue: Tags Not Firing After Import

Check Trigger Configuration:

Open GTM and go to Preview Mode
Click on your site URL
Find your event in the left sidebar
Check which tags fired and which didn’t
For tags that didn’t fire, check:
- Trigger conditions match exactly
- No conflicting triggers blocking it
- Variable values are correct

Common Trigger Issues:

Event name is case-sensitive (page_view ≠ Page_View)
Trigger uses wrong variable type
Additional filters preventing trigger

Data Quality Issues

Issue: Duplicate Events in DataLayer

Possible Causes:

1. Multiple GTM Containers Check if you have more than one GTM container installed:

View page source (Ctrl+U or Cmd+U)
Search for googletagmanager.com/gtm.js
If you find multiple instances, remove the duplicate

2. Manual Tracking Code

Search your theme for custom GA4 or GTM tracking code
Remove any manual event tracking that duplicates ADT events
Keep only the ADT plugin and GTM container

3. Other Analytics Plugins

Disable other analytics plugins temporarily
Check if duplicates stop
Choose either ADT or the other plugin (not both)

Issue: Missing Data in Reports

Event in GTM Preview but Not in GA4:

Wait for Processing

GA4 can take 24-48 hours to show events in standard reports
Use GA4 DebugView for real-time verification
Use Realtime report for recent data (last 30 minutes)

Check Data Filters

In GA4, go to Admin → Data Settings → Data Filters
Ensure your events aren’t being filtered out
Verify internal traffic filter isn’t excluding you

Verify Measurement ID

In GTM, check your GA4 Configuration tag
Ensure Measurement ID (G-XXXXXXXXXX) is correct
Verify tag fires on all pages

Performance Issues

Issue: Site Loading Slowly

Check Event Volume:

// In browser console
window.dataLayer.length

If you see more than 50 events on a single page, you may need to reduce tracking frequency.

Solutions:

Disable Unused Features
- Go to ADT Settings
- Disable features you don’t need
- Focus on essential tracking only
Adjust Scroll Tracking
- If using scroll depth tracking, consider reducing frequency
- Switch from percentage-based to milestone-based tracking
Optimize Video Tracking
- Reduce video milestone frequency
- Track only critical milestones (25%, 50%, 75%, 100%)
Check GTM Container Size
- Remove unused tags from GTM
- Delete old/deprecated triggers
- Clean up unused variables

Issue: Page Load Delayed

GTM loads asynchronously by default, but check:

No Synchronous Tags
- Open GTM → Tags
- Check all tags fire on DOM Ready or Window Loaded (not Page View)
- Never use synchronous scripts in Custom HTML tags
Caching Plugin Conflicts
- Clear all caches (site, CDN, browser)
- Temporarily disable caching plugins
- Test performance without caching first

Consent Management Issues

Issue: Events Fire Before Consent

Verify Consent Integration:

Check which CMP (Consent Management Platform) you’re using
Ensure it’s on the supported list:
- CookieYes
- OneTrust
- Cookiebot
- Complianz
- Borlabs Cookie
- TCF 2.0 compliant CMPs
ADT should auto-detect your CMP
In browser console, check: window.dataLayerBlocked
Should be true until consent is granted

If Events Fire Before Consent:

Your CMP may not be supported
Contact support with your CMP name and version
Consider switching to a supported CMP

Issue: Events Never Fire After Accepting Consent

Check Consent Status:

// In browser console
window.dataLayerBlocked

If this shows true even after accepting cookies, your CMP integration needs attention.

Solutions:

Clear all cookies and test fresh
Verify CMP fires consent events properly
Check browser console for CMP-related errors
Contact support with CMP name and browser console logs

Session Tracking Issues

Issue: Session Summaries Not Firing

Requirements for Session Summaries:

Premium license must be active
Session Manager must be enabled in settings
User must trigger an exit event (navigate away, close tab, etc.)

Test Manually:

// In browser console
window.ADTSession.triggerExit('manual_test')

Then check window.dataLayer for summary events.

Common Issues:

Scripts Not Loading
- Verify premium license is active
- Check browser console for script errors
- Ensure no JavaScript conflicts
Exit Not Detected
- Sessions only summarize on exit
- Try navigating to another page
- Try closing the tab
- Use manual test command above

Issue: Session ID Not Persisting

Check Session Cookies:

// In browser console
document.cookie.split(';').filter(c => c.includes('adt_session'))

You should see an adt_session_id cookie.

If Cookie Missing:

Check if another plugin is blocking cookies
Verify your site allows cookies
Check browser privacy settings
Clear all cookies and test fresh

Common Error Messages

“dataLayer is not defined”

Meaning: Google Tag Manager hasn’t loaded yet or isn’t installed.

Solutions:

Verify GTM container is published
Check GTM container ID is correct
Look for JavaScript errors blocking GTM from loading
Ensure no ad blockers are active (testing only)

“ADTSession is not defined”

Meaning: Session Manager module hasn’t loaded.

Solutions:

Verify premium license is active
Check Session Manager is enabled in settings
Look for JavaScript console errors
Clear browser cache and test again

“Consent not granted”

Meaning: Events are being blocked by consent management (correct behavior).

This is Normal: Events should be blocked until user accepts cookies. If user has accepted and you still see this:

Clear cookies and accept consent fresh
Check if your CMP is supported
Verify CMP integration is working

Getting Additional Help

Diagnostic Information to Collect

When contacting support, please provide:

1. WordPress Environment:

WordPress version
PHP version
Advanced DataLayer Tracker version
Active theme name
List of active plugins

2. Browser Console:

Any red error messages
Complete console log (if possible)
Screenshot of console during testing

3. GTM Configuration:

Container ID
Whether you imported from ADT export
Any custom modifications made

4. Steps to Reproduce:

Exact steps you took
What you expected to happen
What actually happened

Useful Debug Commands

Run these in your browser console to gather information:

// Check ADT loaded
console.log('ADT Version:', window.ADTData?.version);

// Check session
console.log('Session ID:', window.ADTSession?.id());

// View all events
console.table(window.dataLayer);

// Check consent status
console.log('Consent Blocking:', window.dataLayerBlocked);

// Count events
console.log('Total Events:', window.dataLayer.length);

// Check enabled features
console.log('Enabled Features:', window.ADTData?.include);

Still Need Help?

If you’ve tried the solutions above and are still experiencing issues:

Premium Support:

Email: support@datalayer-tracker.com
Response time: Within 24 hours
Include diagnostic information from above

Community Resources:

Documentation: https://datalayer-tracker.com/knowledge-base/
Video tutorials: Coming soon

Last Updated: January 2025
Plugin Version: 1.2.1+

Troubleshooting Guide

Quick Diagnostics

1. Verify Plugin is Active

2. Check Browser Console

3. Verify DataLayer

4. Check GTM Container

Events Not Firing

Issue: No Events Appearing in GTM Preview

Issue: Some Events Fire, Others Don’t

GTM Container Issues

Issue: Container Import Fails

Issue: Tags Not Firing After Import

Data Quality Issues

Issue: Duplicate Events in DataLayer

Issue: Missing Data in Reports

Performance Issues

Issue: Site Loading Slowly

Issue: Page Load Delayed

Consent Management Issues

Issue: Events Fire Before Consent

Issue: Events Never Fire After Accepting Consent

Session Tracking Issues

Issue: Session Summaries Not Firing

Issue: Session ID Not Persisting

Common Error Messages

“dataLayer is not defined”

“ADTSession is not defined”

“Consent not granted”

Getting Additional Help

Diagnostic Information to Collect

Useful Debug Commands

Related Documentation

Still Need Help?

Advanced DataLayer Tracker

Product

Documentation

Company

Quick Diagnostics

1. Verify Plugin is Active

2. Check Browser Console

3. Verify DataLayer

4. Check GTM Container

Events Not Firing

Issue: No Events Appearing in GTM Preview

Issue: Some Events Fire, Others Don’t

GTM Container Issues

Issue: Container Import Fails

Issue: Tags Not Firing After Import

Data Quality Issues

Issue: Duplicate Events in DataLayer

Issue: Missing Data in Reports

Performance Issues

Issue: Site Loading Slowly

Issue: Page Load Delayed

Consent Management Issues

Issue: Events Fire Before Consent

Issue: Events Never Fire After Accepting Consent

Session Tracking Issues

Issue: Session Summaries Not Firing

Issue: Session ID Not Persisting

Common Error Messages

“dataLayer is not defined”

“ADTSession is not defined”

“Consent not granted”

Getting Additional Help

Diagnostic Information to Collect

Useful Debug Commands

Related Documentation

Still Need Help?

Related Articles

Advanced DataLayer Tracker

Product

Documentation

Company