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

Marketing Analytics › Troubleshooting

GTM Data Layer Variable Undefined

Why a GTM data layer variable returns undefined: the push comes too late, the key name or path is wrong, version settings, overwrites, and nested objects.
Troubleshootingintermediate8 min readUpdated

First, find the event where the value disappears

Variables in Tag Manager (GTM) are resolved per event. The same variable can be populated on one event and undefined on the next, and only the event that fires your tag matters. Open preview, run the journey, and select that event in the timeline. In the Variables tab, note the variable's value and type. Then open the Data Layer tab on the same event: it shows the message that created the event and the full model after it was processed. Three readings are possible. The key is absent from the model entirely, which means no push supplied it before this point. The key is present under a slightly different name or path, which means the variable is reading the wrong address. Or the key appears only on a later event, which means the push came too late.

If the key is absent everywhere, type dataLayer into the browser console and read the array. A push that appears in the console but never in preview's model points at a second array or a renamed one. If the variable is fine and the tag still sends nothing, the issue is upstream of the variable; the sibling page on a GTM tag that is not firing covers that branch.

Diagnosis table

Diagnosis

SymptomCheckLikely causeFix
Value present on a later event, undefined on the one that fires the tagTimeline order of the push and the trigger's eventValue pushed after the event that reads itTrigger the tag on the push's own event, or push before the reading event
Key visible in the Data Layer tab, variable still undefinedThe variable's key field against the pushed key: case, spelling, nestingKey name, case or dot path does not match the pushCorrect the key or dot path to the pushed structure
Pushes appear in the console but not in preview's modelWhether the page assigns a fresh array after the container snippetData layer array overwritten instead of pushed toReplace the assignment with a push, guarded so the array is reused
Nested key reads undefined, or keeps an old sibling valueThe variable's version setting and how the object was pushedVersion setting not merging nested values as expectedUse the default version for nested reads and reset objects deliberately
Correct on first load, wrong or empty after in-app navigationThe model on each route-change event in an app-style siteStale values persisting across single-page app viewsReset entity keys in the route-change push and send fresh context
Item fields undefined in e-commerce tagsThe ecommerce object's shape against the tag's expected structureE-commerce object structure differs from what the tag expectsPush the documented items structure and clear the object before each push

Fix, verify and prevent each loss

Pushed too late

The container evaluates triggers when each event arrives. A tag on page view reads whatever the model holds at that moment; if the site pushes page context after the snippet, or pushes the order details a moment after the confirmation page's load event, the tag runs first and finds nothing.

Fix: declare the array and push page context above the container snippet, and for interaction data, attach the tag to a custom event trigger on the push itself, which is the timing table in the data layer guide.

Verify: on the event that now fires the tag, the variable holds the value and its type is right.

Prevent: record a trigger moment for every key in the push contract, so developers know a value is needed before the event and not merely somewhere on the page.

Wrong address

The data layer variable's key field is case-sensitive and follows the object's nesting with dots. A push of transactionId is not transaction_id; a key inside ecommerce is read as ecommerce.transaction_id, not as the bare key.

Fix: copy the exact path from the Data Layer tab into the variable's key field, then rename the key in the site code if the plan says it should be different, rather than adding a second variable as a translation.

Verify: the Variables tab shows the value on the firing event.

Prevent: keep one naming style for keys, matching the event parameter names the destination already documents, as the tags, triggers and variables guide recommends for data layer variables.

The array was replaced

The container watches the array it found or created when the snippet ran. A script, plugin or theme that later assigns a brand new array to the same global name detaches every subsequent push from the container: the console shows the values, the container never hears them.

Fix: change every assignment after the snippet into a push, and make the declaration reuse an existing array rather than replace it, exactly as the declaration line in the data layer guide does.

Verify: pushes made after the snippet now appear as events and in the model in preview.

Prevent: search the codebase and any platform plugins for assignments to the array name during review, and test after every plugin update, since plugins are the usual culprit.

Version setting surprises

The data layer variable offers two reading modes. The default mode treats dots as a path and merges nested objects across pushes, so context pushed early stays readable later; the older mode reads keys literally and does not merge. A variable switched to the older mode can return undefined for a dotted path that works in the default one, and a variable in the default mode can return a stale sibling key that was never reset.

Fix: use the default mode for nested reads, and push a reset for objects that must not carry over, as explained under data layer variables in the tags, triggers and variables guide.

Verify: the value on the firing event matches the latest push, with no leftovers from an earlier one.

Prevent: leave the version setting alone unless a documented reason exists, and note that reason in the variable's description.

Stale values on app-style sites

After the first load, an app-style site changes views without reloading. Because the model merges, a product ID pushed on a product view can persist onto the next category view, and a reset pushed before the new values arrive leaves the key empty for any tag that fires in between.

Fix: make the router's view push carry both the reset and the new context in the right order, and trigger view tags on that push; the route-change section of the data layer guide describes the pattern.

Verify: navigate between several routes in preview and read the variable on each view event.

Prevent: add a navigation sequence to the release test, not just a first page load.

E-commerce shape mismatch

GA4 e-commerce tags expect an ecommerce object with an items array built from the documented item fields. A legacy structure with an extra nesting level, an items list under another name, or prices sent as strings leaves item variables undefined or the reports empty.

Fix: align the push with the item contract in the e-commerce tracking tutorial, clear the object with a null push before each event, and let the tag read the object directly instead of mapping each field.

Verify: the event arrives in debug view with its items and values intact.

Prevent: keep a literal example push for each e-commerce event in the tracking plan and test every template against it.

Prevention: a data layer contract with tests

Undefined variables are contract failures: the analyst expected one key and the site sent another, or sent it at another moment. The routine that prevents them has three layers. First, a written push specification for every event: name, trigger moment, every key with its type and nesting, and a literal example. Second, a browser check on release day: open preview, run each journey, and confirm on the firing event that every variable the tags read is populated. Third, automated tests in the site's own codebase that assert each action produces a push of the agreed shape, so a refactor that renames a key fails the build instead of the report. Give each variable a default that reads as an obvious placeholder, and watch reports for it; the placeholder turning up in a dimension is the earliest warning that a push has drifted. Revenue, leads and the other headline measures (KPI) depend on these values, so treat a failed check as a release blocker rather than a ticket for later. The Tag Manager hub links the governance pages that keep the specification current.

Illustrative example — not a real result

A purchase value that vanished on one template

An outdoor-equipment shop sees value arrive as undefined on 38% of purchases in its GA4 debug checks. Preview on the confirmation page shows the tag firing on the purchase event, with the variable ecommerce.value undefined. The Data Layer tab shows the push nested as ecommerce.purchase.value, a structure left over from an older implementation on the express-checkout template only; the standard template pushes the documented shape. The developers align the express template with the standard push and add a null reset before it. After release, 2 test orders through each template show the value populated on the firing event, and the next full day records 214 purchases, all with values.

Common mistakes

Reading the variable on the wrong event. Creating a second variable to translate a misnamed key instead of fixing the push. Assigning a new array in a plugin after the container has loaded. Switching the version setting to make one read work and breaking nested reads elsewhere. Testing only the first page load of an app-style site.

Frequently asked questions

The value is visible in the console, so why does the variable still say undefined?

The console shows the array as it is now, after every push. The variable is resolved per event, at the moment that event is processed. If the push arrived after the event you are inspecting, the value existed later but not then. Select the exact event that fires the tag in preview and read the Variables tab there, not on the latest event in the timeline.

Should I set a default value so the tag stops sending undefined?

A default keeps the literal word undefined out of reports, which is worth doing, but it hides the fault rather than fixing it. Set a default that is obviously a placeholder, such as a value reading not provided, so a missing push still shows up in reports as something to investigate instead of blending in with real values.

Does the variable name in Tag Manager have to match the key in the push?

The display name of the variable can be anything. What must match is the data layer variable name field inside it, which is the key or dot path to read. That field is case-sensitive and must follow the exact nesting of the pushed object, so a key pushed inside an object needs the object name, a dot and the key.

Terms used on this page

Where this page is used

Also related

Sources

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

Related