Why does my Custom Dimension show ‘undefined’ or ‘Value not defined’ in Matomo?

If you are tracking data with Custom Dimensions and reports are showing the dimension value as undefined or value not defined, it indicates how the tracking code handled the value before sending it to Matomo. These messages do not mean tracking has failed, it shows the dimension value was unavailable or left empty at the time the tracking request was sent.

This guide explains what each message means and how to resolve it.

• undefined: Occurs when the tracking code tries to send a Custom Dimension, but the variable or value is not yet defined in JavaScript. For example, _paq.push(['setCustomDimension', 1, myVariable]);
• Value not defined: Displays when the tracking code explicitly sends an empty string as the value. If you intentionally set the dimension to an empty value, then Value not defined appearing in reports is expected behaviour. For example, _paq.push(['setCustomDimension', 1, '']);
  

How to check the variable definition

1. The undefined message occurs when the variable or value is not yet defined in JavaScript. Confirm that the variable exists and holds a value before calling setCustomDimension.
2. Review the firing order of your scripts to ensure variables are defined first.
3. To prevent empty strings ('') appearing as Value not defined in reports, only set the Custom Dimension if the variable exists and has a value.
4. You could optionally add a fallback value by using a default placeholder when the variable is empty. This prevents empty strings from being sent and makes missing data easier to identify in reports. For example, _paq.push(['setCustomDimension', 1, myVariable || 'unknown']);
5. If using Matomo Tag Manager, use Preview / Debug mode to review the order in which your tags are firing and check the variable definitions are correct.

By identifying whether a Custom Dimension is recorded as undefined or Value not defined, you can diagnose whether the issue stems from a missing variable, a timing error, or an intentionally empty value.