Skip to content
Faisal Mahmud TusherDigital marketing, SEO & analytics
with Faisal Tusher

Marketing Analytics › Google Tag Manager

Debugging with Preview Mode

A step-by-step tutorial for debugging GTM: connecting preview mode, the event timeline, tags fired, variables and data layer views, and GA4 DebugView.
Tutorialbeginner11 min readUpdated

Before you start

  • Edit access to the container. Preview runs from a workspace, so you need at least edit rights on the GTM container. Read-only users can view a shared debug session but cannot start one.
  • The building blocks. The tags, triggers and variables guide explains what you will be looking at; preview mode is far easier to read when you know what a trigger condition is before you see one evaluated.
  • A written test scenario. The page, the action and the tag that should fire, with the parameters it should carry. Debugging without a target turns into browsing. If the tag is a GA4 event, the GA4 through GTM tutorial shows how it should have been built.
  • A clean browser profile. Ad blockers, privacy extensions and strict tracking protection interfere with both the container and the debugger. Use a profile without them, or allow your site and Tag Assistant.
  • Pop-ups allowed for your domain. Preview opens your site in a new window and keeps a debug connection alive between the two; a blocked pop-up is the most common reason the connection never starts.
  • Access to the GA4 property. DebugView lives in the property's admin area, and you need a role that can open it. Without it you can still verify requests in the browser, but not what the property accepted.

The walkthrough

The steps run in the order a session naturally follows: connect, find the event that should have fired the tag, see what the tag did, then work downwards through variables, data layer and errors until the cause is visible. The last steps take the investigation outside Tag Assistant, into GA4 DebugView and the browser itself, and then make the whole session shareable.

  1. Connect preview mode

    Open the workspace that holds the changes you want to test and click Preview. Tag Assistant asks for the URL of the page to debug; enter the exact page, including any query string the test depends on, and connect. Your site opens in a new window with a small badge confirming the debugger is attached, and Tag Assistant starts listing events. If the badge never appears, the usual causes are a blocked pop-up, a site that strips query parameters during a redirect, or a browser blocking the storage the connection relies on. Google documents a companion browser extension for Chrome that keeps the connection alive in those cases; install it before spending time on anything else. Remember that what you are previewing is the draft workspace, not the version visitors receive.

  2. Read the event timeline

    The left-hand column is a timeline of everything the container saw on the page, in order. Every page starts with the same lifecycle events, shown as Container Loaded, DOM Ready and Window Loaded, which correspond to the gtm.js, gtm.dom and gtm.load events in the data layer. Below them come the built-in interaction events (clicks, link clicks, form submissions, history changes, scroll depth, timers, video) as you perform them, and any custom events pushed by the site's code under the names your developers chose. Perform the action from your test scenario and watch which event appears. If nothing appears, the site never told the container anything, and the problem is upstream of any tag. The Summary entry at the top aggregates every tag across all events on the page, useful for a quick "did it fire at all" check.

  3. Inspect the Tags tab

    Select the event that should have fired your tag and open the Tags tab. It is split into tags that fired on this event and tags that did not. Click the tag you care about. The panel shows the tag's resolved properties, with every variable replaced by its value at the moment of firing, and the firing triggers with each condition marked as met or not met. A tag in the "not fired" list with one red condition tells you exactly which comparison failed; a tag with all conditions green but still listed as not fired usually has an exception trigger or a consent requirement holding it back, which the same panel shows. Check the tag's properties too: a GA4 event tag that fired with the wrong measurement ID or a blank parameter looks healthy in the list and is still wrong.

  4. Check variable values

    The Variables tab lists every built-in and user-defined variable with its value and type for the selected event. Read it when a trigger condition failed for a reason you cannot see, or when a tag fired but carried the wrong value. Three faults account for most findings. A data layer variable returns undefined because the key name differs in case or nesting from what the site pushed. A value arrives as a string where a number was expected, or the reverse, so a comparison in the trigger behaves differently from what you intended. A variable is correct on the page view but empty on the later event you are inspecting, because it was read at a moment when the data had not yet been pushed. Variables are evaluated per event, so always check them on the event that fires the tag, not on the first one in the timeline.

  5. Read the Data Layer tab

    The Data Layer tab shows the message that created the selected event and the full state of the data layer after it was processed. This is where the developer contract is verified: compare the keys, nesting and value types against what the data layer guide specifies for your site, and against what your variables expect. Common findings are an object that was pushed with a different event name from the one the trigger listens for, an e-commerce items array that is empty or nested one level too deep, and a push that happens before the container snippet so the event is recorded but the state view shows that the values were overwritten by a later push. On single-page applications, check that route changes push a fresh event and that old values from the previous view are cleared rather than carried forward.

  6. Open the Errors tab

    The Errors tab lists JavaScript errors thrown by tags and custom JavaScript variables, with the tag or variable responsible and the event it happened on. A custom HTML tag with a syntax error, a variable that references a property of an undefined object, or a vendor script that fails to initialise all surface here rather than silently. An error in one tag does not stop the others, so a container can look healthy in the Tags tab while a single tag has been failing on every page for months. Make a habit of glancing at this tab on every event you inspect, and treat any entry as a defect to fix before publishing, even when it is not the tag you came to debug.

  7. Confirm arrival in GA4 DebugView

    Tag Assistant tells you the tag fired; it cannot tell you the property accepted the event. Open the GA4 property's admin area and go to DebugView. Devices in debug mode appear in a selector; preview mode puts your browser into debug mode automatically, so your session should be listed. The stream shows events as they arrive, and clicking one reveals its parameters and the user properties attached. Check three things: that the event name matches what the tag sent, that every parameter you set is present with the expected value, and that the event is not accompanied by an unexpected duplicate from a second tag or a hard-coded snippet. If the device is missing, confirm the measurement ID, look for an internal traffic rule excluding you, and verify in the next step that the request actually left the browser.

  8. Use the browser network and console

    Open the browser's developer tools alongside the preview. In the network panel, filter requests by collect to see GA4 hits leaving the page; the payload of each request lists the event name under en and event parameters with an ep. prefix, which lets you confirm what was transmitted independently of either debugger. A request that never appears means the tag was blocked or errored; a request that returns an error status means the endpoint rejected it. In the console, typing dataLayer prints the full array of pushes in order, which is the quickest way to see what the site pushed before the container loaded. Console errors from the site's own scripts also matter: a page error before the data layer push explains an event that never arrived. When the push or tag under test was drafted by an AI tool, the routine for checking AI-written tracking code adds the checks preview cannot make on its own: names against the tracking plan, personal data in values and pages that should not match.

  9. Share the debug session

    Tag Assistant can generate a share link for the preview of your workspace. The link lets a colleague, a developer or a client load your site with the same draft container attached and see their own debug session, without needing edit rights to the container. Use it to hand a reproducible case to whoever owns the fix, with your written scenario and the event name to look for. Shared previews expire, and they expose draft changes to anyone holding the link, so share with people rather than channels and start a fresh link after the fix lands. Once the tag behaves correctly for every case in your scenario, publish the workspace with a version note that says what was tested, and re-run the key checks on the live container. The GTM container publish checklist collects those pre-publish checks in one list to tick. Preview keeps a draft away from visitors, but a real purchase completed during the test still counts and still reaches the ad platforms; the guide to test environments and test data for marketing tools covers marked test records and the exclusions that keep test orders out of reports.

Troubleshooting table

The faults below cover most sessions. Each row names the first thing to check; several link to the deeper guides where the fix lives. Problems that originate inside the property rather than the container are collected in the common GA4 mistakes guide.

SymptomLikely causeWhat to check
Debug badge never appears on the sitePop-up blocked, redirect strips parameters, or storage blockedAllow pop-ups; enter the final URL; install the companion extension
Event missing from the timelineSite never pushed it, or pushed before the container loadedConsole dataLayer; timing of the push relative to the snippet
Tag listed as not fired, one condition redTrigger condition compares the wrong variable or valueVariables tab on that event; case and type of the value
Tag not fired, all conditions greenException trigger or consent requirement blocking itTag's exceptions; consent settings on the tag
Tag fired, wrong value sentVariable read on the wrong event or mapped to the wrong keyData Layer tab for the event; variable key path
Tag fired twiceTwo triggers on one tag, or a hard-coded snippet duplicating itSummary view; network panel for duplicate requests
Fires in preview, not after publishingPublished the wrong workspace, or the live page differs from the test pageVersion contents; retest the live container
DebugView empty while Tag Assistant shows the tagWrong measurement ID, internal traffic filter, or request blockedNetwork panel; property data filters
Errors tab lists a custom HTML tagScript error inside the tagFix the tag or replace with a template
Illustrative example — not a real result

A purchase event that fired twice on one order

A retailer notices in DebugView that one test order produced two purchase events with the same transaction ID, inflating revenue by 100% for that order. In preview mode, the Summary view shows the GA4 purchase tag fired on two events: the custom purchase push and a second push named checkout_complete that the site's developers added during a redesign. Both carry the same ecommerce object, and the tag's trigger was set to fire on either event name. The Data Layer tab confirms the two pushes arrive 0.4 seconds apart with identical contents. The fix is to remove the obsolete event from the trigger, retest with 3 orders in preview to confirm a single purchase per transaction, and publish with a version note recording the duplicate.

If debugging reveals that live tracking has already failed, follow the tracking outage response SOP to protect bidding, inform stakeholders and record the gap in reporting.

When preview shows a tag that should run sitting in the not-fired list, or firing only in the draft, the diagnosis page for a GTM tag that is not firing works through each cause from what these panes show.

Common mistakes

  • Debugging the published container by mistake. Preview shows the workspace draft; make sure the changes you think you are testing are actually in that workspace.
  • Looking at the wrong event. Variables and data layer state are per event. The value on the page view is irrelevant if the tag fires on a click.
  • Stopping at "tag fired". Fired is not received. DebugView and the network panel close the loop.
  • Ignoring the Errors tab. A failing custom HTML tag does not announce itself anywhere else.
  • Testing with blockers enabled. A privacy extension produces faults that do not exist for most visitors.
  • Testing one path only. Logged-in and logged-out, mobile and desktop, first visit and return visit often push different data.
  • Publishing without a version note. The next person debugging has no idea what was changed or why.
  • Treating preview as the only quality check. It validates a session, not a population. The marketing data quality guide covers the ongoing monitoring that catches what preview cannot, and the conversion rate you report depends on both.

The Tag Manager hub lists the other guides in this section, including the build-side pages that preview mode tests.

Frequently asked questions

Does preview mode show the published container or my unpublished changes?

It shows the workspace you started preview from, including every unpublished change in it. That is the point: you test the draft before publishing. If you need to debug what visitors currently receive, preview from a workspace with no pending changes, or compare the workspace against the latest version first so you know what differs.

Why do events show in Tag Assistant but not in GA4 DebugView?

DebugView only lists events that arrive with debug mode enabled, and only for the property the tag points at. Check the measurement ID on the tag, confirm the request leaves the browser in the network tab, and check that consent settings are not blocking the tag in your test region. If the request is sent but DebugView stays empty, the device may be excluded by an internal traffic filter.

Can I debug a container on a page I cannot log in to, such as a client's site?

You need edit access to the container, not to the site. Preview mode works on any page that loads the container, and the shared debug link lets a colleague or client see the same session without edit rights. What you cannot do is preview changes to a container you have no access to; in that case the owner has to share preview from their workspace.

Terms used on this page

Where this page is used

Part of these learning paths

Also related

Sources

  1. Preview and debug containers — Google Tag Manager Help
  2. Google Tag Manager Help — Google Tag Manager Help

Related