Effective Debugging Methods in Tealium iQ: A Practical Guide

Debugging Approaches in Tealium iQ

It’s important to understand that debugging in Tealium isn’t limited to a single tool. Since Tealium processes data through multiple stages such as the data layer, extensions, load rules, tags, and vendor requests you’ll often need to use different debugging techniques depending on where the issue occurs.

For example:

• If a variable is missing, you’ll inspect the data layer.

• If an extension isn’t executing, you’ll debug the extension scope and execution order.

• If a tag isn’t firing, you’ll investigate the load rule.

• If the tag fires but the vendor doesn’t receive the expected data, you’ll inspect the network request.

• If you’re debugging server-side events, Tealium Trace is the preferred tool.

Rather than relying on a single method, experienced Tealium developers follow a structured debugging process, moving through each stage of the execution flow until the root cause is identified.

If utag.jsfails to load, none of the configured tags or extensions will execute, making this the most important initial check during debugging.

1. Open your website in the browser.

2. Press F12 (Windows/Linux) or Cmd + Option + I (macOS) to open the browser’s Developer Tools.

3. Navigate to the Network tab.

4. Refresh the page.

5. In the filter box, search for:

If Tealium is loading correctly, you should see a request similar to:

A successful request (typically with a 200 status code) confirms that Tealium has been loaded successfully and can continue processing the page.

If you don’t see a request for utag.js, it indicates that Tealium has not been loaded. Some common causes include:

• The Tealium script has not been implemented on the page.

• The page is pointing to an incorrect environment or profile.

• Recent code changes accidentally removed the Tealium snippet.

• A Content Security Policy (CSP) is blocking the request.

• A browser extension, such as an ad blocker or privacy tool, is preventing the script from loading.

• A JavaScript error occurring earlier on the page is interrupting execution.

Until utag.js loads successfully, there is little value in checking load rules, extensions, or tag mappings, as none of these components can execute without the Tealium library.

Once you’ve confirmed that utag.js is loading correctly, the next step is to verify that you’re testing the correct Tealium environment and that the expected version of your implementation has been published.

Before diving into debugging, make sure you’re testing the correct Tealium environment.

• Verify whether you’re testing Dev, QA, or Prod.

• Confirm that the correct utag.jsfile is loading.

• Check that your latest changes have been saved and published to the environment you’re testing.

A common issue is testing an older published version while expecting newly added changes.

Every tag depends on the data available in the Universal Data Object.

In the browser console, inspect the data:

Verify that:

• Required variables exist.

• Variable names are correct.

• Values are populated as expected.

• Data types are correct.

Missing or incorrect variables frequently prevent load rules from evaluating successfully.

After confirming that the required data is available in the Universal Data Object (UDO), the next step is to verify whether the tag’s Load Rule is evaluating correctly.

Load Rules determine whether a tag is eligible to fire. Even if the tag configuration and mappings are correct, the tag will not execute if the Load Rule conditions are not satisfied.

For example, consider a Load Rule:

If the data layer contains:

the condition passes and the tag can fire.

However, if the value is:

the condition may fail because the value does not exactly match the configured rule.

When validating Load Rules, check:

• Are all required variables available in utag.data?

• Do the variable values exactly match the expected conditions?

• Are AND/OR conditions configured correctly?

• Is the Load Rule assigned to the correct tag?

Common Load Rule issues include:

• Missing data layer variables

• Incorrect capitalization or spelling

• Unexpected values from the website

• Incorrect rule logic

• Testing against an outdated published version

You can use the browser console to verify the data:

You can also enable Tealium debugging:

to view whether tags are loading or being skipped due to Load Rule conditions.

If a tag is not firing, always confirm the Load Rule first before investigating the tag configuration itself. Many tag firing issues are caused by conditions not being met rather than a problem with the tag.

After validating Load Rules, the next step is to check whether Tealium Extensions are working as expected. Extensions are used to modify, enrich, or transform data before it is passed to tags and vendor platforms.

A tag may have the correct configuration, and the Load Rule may evaluate successfully, but an extension issue can still cause incorrect data to be sent or prevent the expected behavior.

Common extension-related issues include:

• Extension is not executing.

• Incorrect extension scope.

• Incorrect execution order.

• Data being overwritten by another extension.

• JavaScript errors inside custom extensions.

• Extension logic not matching the current page or event conditions.

Common scopes include:

• Before Load Rules

• After Load Rules

• Tag Scoped

• DOM Ready

The scope is important because an extension may run before or after certain Tealium processes.

For example, if an extension creates a variable that is required for a Load Rule, but the extension runs after Load Rules are evaluated, the tag may not fire because the required data is not available at the right time.

When multiple extensions modify the same variable, the execution order can affect the final value.

Example:

Extension 1:

Extension 2:

In this case, the final value depends on which extension runs last.

Always verify the order of extensions when the data being sent does not match the expected value.

Custom JavaScript Extensions can introduce errors that prevent data from being processed correctly.

Use console logging to check the values available inside an extension.

Example:

Expected output:

If the output is:

the issue may be with the data layer or the extension logic.

You can use the following tools to troubleshoot extension issues:

Browser Console

Check the available data:

This helps verify whether the extension is creating or modifying the expected variables.

Tealium Debug Mode

Enable Tealium debugging:

This provides additional information about Tealium execution, including tag loading and extension behavior.

Tealium Web Companion / Tealium Tools

These tools help review the implementation flow and identify whether extensions are executing as expected during page loads and events.

Extensions can change the data before it reaches a tag. If a tag is not firing or the vendor receives unexpected values, always verify whether an extension is modifying, removing, or creating the data incorrectly.

The browser’s Developer Tools are one of the most powerful debugging resources when troubleshooting Tealium iQ implementations. Before making changes in Tealium iQ, many issues can be identified directly from the browser by inspecting data, scripts, HTML elements, and network requests.

To open Developer Tools:

• Windows/Linux: F12 or Ctrl + Shift + I

• macOS: Cmd + Option + I

You’ll mainly use four tabs:

• Elements

• Console

• Network

• Sources

Each tab helps investigate a different part of the tracking process. The Console helps validate data and JavaScript execution, the Network tab confirms whether requests are being sent, the Elements tab helps debug page interactions, and the Sources tab helps troubleshoot JavaScript execution.

The Console allows you to inspect Tealium objects, validate variables, and identify issues while the page is running.

For example, type:

You’ll see the complete Tealium object.

Now inspect the data layer.

Example output:

{
  page_name: "Home",
  page_type: "Landing",
  user_type: "Guest",
  country: "India"
}

The Console allows you to verify the current Tealium state, inspect variables, and identify missing or unexpected values during debugging.

If instead you see:

it indicates that the variable is not available at that point in the data layer and needs further investigation.

Instead of viewing the whole object, inspect a single variable.

Output:

or

This is useful when troubleshooting a specific variable used in:

• Load Rules

• Extensions

• Tag mappings

• Vendor parameters.

Inside JavaScript Extensions, Tealium stores event data in a variable called b.

Example: