📋 Scenario Tester error guide

This guide covers the error messages you can encounter in the Scenario Tester, what they mean and how to solve them.

What will you find in this guide?

• An explanation of every DataLayer Guard error after running the Scenario Tester
• The most common causes per error
• Steps to resolve each issue
• A troubleshooting table per error

🔧 Applies to: Datalayer Guard Scenario Tester

Introduction

When DataLayer Guard Scenario Tester runs a scenario, it validates each step in sequence. If something goes wrong, like a page failing to load, an action not executing, or a datalayer event being missing or incorrect, its gives you an error.

⚠️ Important: Always check the step number in the error first. It tells you exactly where something went wrong in the scenario.

1. Error: Could not open the starting page

The DataLayer Guard could not open the starting page before running any steps.

Why does this happen?

• The URL is behind a login, VPN, or firewall
• The URL contains a typo or the page does not exist
• The URL type (hostname, page URL, page path) does not match what was selected in the scenario settings
• The server is down or returning an error

How to fix it

1. Open the scenario in the portal and check the Starting URL.
2. Paste the URL into an incognito browser window and see if it loads.
3. Make sure the page opens without a login screen or redirect.
4. Check that the URL type matches the format you entered.
5. If the page requires a login, use a publicly accessible staging URL instead.

💡 Tip: Test the URL on a different device or network. If it does not load there either, the problem is with the page, not the scenario configuration.

Troubleshooting

2. Error: Unable to load the page

The DataLayer Guard started the scenario but could not load a page during one of the steps.

Why does this happen?

• The URL in the step is wrong or no longer exists
• The page returns an error (404, 500)
• The page redirects somewhere unexpected
• The server is slow or unresponsive

How to fix it

1. Find the step number in the error and open the scenario.
2. Check the URL in that step.
3. Open the URL in a browser and look for errors or unexpected redirects.
4. If the URL uses a relative path, check that the base domain in the scenario settings is correct.
5. Update the URL and re-run the scenario.

💡 Tip: The error includes the exact URL the Guard tried to open. Copy it directly into your browser to reproduce the issue.

Troubleshooting

3. Error: Page did not load in time

The DataLayer Guard reached the URL but the page did not finish loading before the timeout.

Why does this happen?

• The server responds slowly
• The page loads heavy assets like large images or scripts
• A third-party script is blocking the page from rendering
• A network issue between the Guard and the server

How to fix it

1. Find the step from the error and check how fast that page loads using Google PageSpeed Insights or WebPageTest.
2. Look for blocking scripts that delay rendering.
3. Increase the timeout for the scenario or the specific step.
4. Defer or lazy-load heavy assets if you can.
5. If the page is always slow, test with a lighter page where the dataLayer still fires.

⚠️ Important: If this only happens occasionally, it could be server load or network instability. Run the scenario again before making changes.

Troubleshooting

4. Error: Step action failed

The DataLayer Guard loaded the page but could not complete the action in the step.

Why does this happen?

• The element (button, link, input field) was not found on the page
• The element exists but is hidden, disabled, or covered by something else
• The page layout changed and the selector no longer works
• A previous step failed, which caused this step to break as well
• The element had not loaded yet when the action was triggered

How to fix it

1. Check which action failed and on which page.
2. Open that page and confirm the element is there and clickable.
3. If the selector uses a dynamic attribute like an auto-generated ID, switch to a stable one like a data- attribute or visible text.
4. Add a wait before the action if the element loads dynamically.
5. Check if the steps before this one completed successfully, since a failing step earlier can break the steps that follow.

💡 Tip: Open DevTools (right-click > Inspect) and test your selector in the console to confirm it matches the right element. To test the selector you can use the “document.querySelectorAll(’<selector>’)”

Troubleshooting

5. Error: Datalayer not found

The DataLayer Guard loaded the page but could not find the datalayer variable.

Why does this happen?

• The dataLayer is not initialized on this page
• The dataLayer uses a different variable name like customDataLayer or window.dl
• The GTM container is missing from this page
• The dataLayer loads after the Guard already checked for it

How to fix it

1. Open the page in a browser and type window.dataLayer in the DevTools console. It should return an array.
2. If the page uses a different name, update the variable name in the scenario settings.
3. Check the page source for the GTM snippet (googletagmanager.com).
4. If the datalayer loads late, make sure GTM fires early in the <head>

Troubleshooting

6. Error: Datalayer parameter error

The DataLayer Guard found the datalayer and the event, but a parameter did not match the template.

The error shows:

• Parameter name: the key that failed
• Expected type: the type defined in your template (e.g. string, number)
• Actual type: the type that was actually pushed
• Expected value: the value your template expects
• Actual value: the value that was pushed

Why does this happen?

• A number is pushed as a string ("42" instead of 42)
• The value does not match the pattern in the template
• There is a typo in the parameter name in the push or the template
• A dynamic value like a product ID is undefined or null at the time of the push
• The template and the implementation are out of sync

How to fix it

1. Read the error carefully and note the parameter name, expected type, expected value, actual type, and actual value.
2. Open the page where the event fires and check the datalayer in the DevTools console with window.dataLayer.
3. Find the event and compare the parameter against your template.
4. Fix the mismatch by updating the datalayer push in your implementation, or adjust the template if the change was intentional.
5. Re-run the scenario to confirm the fix.

💡 Tip: Filter the event in the console with dataLayer.filter(e => e.event === 'your_event_name') to see the exact structure being pushed.

❓ Note: If multiple parameters are wrong, the Guard only reports the first one. Fix it and re-run to check for any remaining issues.

Troubleshooting

✅ Verify your setup

After fixing an error, always re-run the full scenario to confirm everything passes.

1. Save your changes in the portal or in your dataLayer implementation.
2. Go to the DataLayer Guard scenario overview and click Run scenario.
3. Check the step results. All steps should show a green status.
4. Confirm all events and parameters pass in the validation results.
5. If a new error shows up, use this guide to find and fix it.

⚠️ Important: Always publish your GTM container after making changes. Unpublished changes will not be picked up by Datalayer Guard.

What's next?

• Set up alerts to get notified when a scenario fails in production
• Connect your results to BigQuery for historical analysis
• Create multiple scenarios to cover different user flows like product pages, checkout, or login