---
title: "Debugging Calculations in GravityM​ath"
date: 2026-04-23
author: "GravityKit"
link: "https://www.gravitykit.com/docs/gravitymath/debugging-calculations/"
---

Things don't always work as they should! GravityMath includes built-in debugging to help you identify calculation issues. When a calculation doesn't work, the shortcode output is typically invisible. Debugging reveals what went wrong and why.

Debug messages are only shown to site administrators (users with the `edit_others_posts` capability), so visitors will never see error messages.

## Three Ways to Enable Debugging

### 1. Add `debug="true"` to the Shortcode

Add the `debug="true"` parameter directly to your `[gravitymath]` shortcode:

```
[gravitymath scope="entry" debug="true"] {Number:1} + {Number:2} [/gravitymath]
```

```
[gravitymath scope="entry" debug="true"] {Number:1} + {Number:2} [/gravitymath]
```

This is the most common method and is useful when troubleshooting a specific shortcode. The screenshot below shows `debug="true"` added to a shortcode inside a GravityView Custom Content field:

![Screenshot of the “Options: Custom Content” modal in WordPress showing a text area with the shortcode [gv_math debug=](https://www.gravitykit.com/wp-content/uploads/2026/04/file-DWQMAcTIbj.png)
Custom Content settings displaying a gv\_math shortcode with debug mode enabled.

### 2. Add `?gravitymath_debug=true` to the Page URL
Append `?gravitymath_debug=true` to any page URL to enable debugging for **all** GravityMath shortcodes on the page — without editing any shortcode attributes.

For example:

```
https://example.com/my-page/?gravitymath_debug=true
```

```
https://example.com/my-page/?gravitymath_debug=true
```

This is helpful when you want to quickly debug a page without modifying shortcodes, or when the shortcodes are embedded inside GravityView Custom Content fields where editing is less convenient.

*Note: The older* `?gv_math_debug=true`  *parameter also works for backwards compatibility.*

### 3. Enable via PHP Constants

If both `WP_DEBUG` and `GRAVITYMATH_DEBUG` are set to `true` in your `wp-config.php` , debugging will be enabled automatically for all GravityMath shortcodes:

```
define( 'WP_DEBUG', true );
define( 'GRAVITYMATH_DEBUG', true );
```

```
define( 'WP_DEBUG', true );
define( 'GRAVITYMATH_DEBUG', true );
```

When using PHP constants, the debug output visibility follows the `WP_DEBUG_DISPLAY` setting.

*Note: The older* `GV_MATH_DEBUG`  *constant also works for backwards compatibility.*

## What Debugging Shows

When debugging is active, you will see:

- **Numbered links** (e.g., , ) displayed next to each calculation result in the View
- **A detailed error report** at the bottom of the page listing each error with an "(Additional info)" link for more details

The screenshot below shows a star data table where each row's "Number of Days" column has a numbered debug link. Below the table, the report lists errors — in this case, the merge tags were not replaced because `scope="entry"` was missing from the shortcode, so the formula `{Distance in Light Years:12} * 365.25` could not be evaluated:

![A GravityView table of star data showing numbered debug links in the Number of Days column, with error messages below reporting unrecognized token errors because scope=entry was not set](https://www.gravitykit.com/wp-content/uploads/2018/01/example-of-debugging-messages.png?1470956084)

## Common Error Messages

- **"Unrecognized token"** — The formula contains text that could not be parsed as a number or math operation. This usually means merge tags were not replaced — check that the correct `scope` is set.
- **"scope requires an ID to process the formula"** — The shortcode has a `scope` attribute but is missing the required `id` attribute.
- **"Invalid field"** — The field ID referenced in your formula doesn't exist in the form. The debug link will point to the form editor.
- **"Calculation error"** — The formula has a syntax error or produced an invalid result. The report will show the processed formula and error trace.
- **"Empty formula"** — No formula was found. Check that your shortcode has content between the opening and closing tags, or that the `formula` attribute is set.

## Developer Reference

### [`gravityview/math/debug` ](https://www.gravitykit.dev/docs/gravitymath/filters/gravityview-math-debug/) Filter

Use this filter to programmatically enable or disable debugging:

```
// Always enable debug for administrators
add_filter( 'gravityview/math/debug', '__return_true' );

// Always disable debug
add_filter( 'gravityview/math/debug', '__return_false' );
```

```
// Always enable debug for administrators
add_filter( 'gravityview/math/debug', '__return_true' );

// Always disable debug
add_filter( 'gravityview/math/debug', '__return_false' );
```

See the [full filter documentation](https://www.gravitykit.dev/docs/gravitymath/filters/gravityview-math-debug/) for details.

### `notices` Shortcode Attribute

The `notices="true"` attribute shows inline warning/error notices to end users without the full debug report:

```
[gravitymath scope="form" id="1" notices="true"] {Number:1:sum} [/gravitymath]
```

```
[gravitymath scope="form" id="1" notices="true"] {Number:1:sum} [/gravitymath]
```