Before you start
- Edit access to the container. Preview runs from a workspace, so you need at least edit rights on the GTMTag management system. 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 GA4Google's event-based analytics platform. DebugView and the browser itself, and then make the whole session shareable.
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.
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.domandgtm.loadevents 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.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.
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
undefinedbecause 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.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
itemsarray 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.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.
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.
Use the browser network and console
Open the browser's developer tools alongside the preview. In the network panel, filter requests by
collectto see GA4 hits leaving the page; the payload of each request lists the event name underenand event parameters with anep.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, typingdataLayerprints 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.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.
| Symptom | Likely cause | What to check |
|---|---|---|
| Debug badge never appears on the site | Pop-up blocked, redirect strips parameters, or storage blocked | Allow pop-ups; enter the final URL; install the companion extension |
| Event missing from the timeline | Site never pushed it, or pushed before the container loaded | Console dataLayer; timing of the push relative to the snippet |
| Tag listed as not fired, one condition red | Trigger condition compares the wrong variable or value | Variables tab on that event; case and type of the value |
| Tag not fired, all conditions green | Exception trigger or consent requirement blocking it | Tag's exceptions; consent settings on the tag |
| Tag fired, wrong value sent | Variable read on the wrong event or mapped to the wrong key | Data Layer tab for the event; variable key path |
| Tag fired twice | Two triggers on one tag, or a hard-coded snippet duplicating it | Summary view; network panel for duplicate requests |
| Fires in preview, not after publishing | Published the wrong workspace, or the live page differs from the test page | Version contents; retest the live container |
| DebugView empty while Tag Assistant shows the tag | Wrong measurement ID, internal traffic filter, or request blocked | Network panel; property data filters |
| Errors tab lists a custom HTML tag | Script error inside the tag | Fix the tag or replace with a template |
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.
