Debug - Liquid Tag Reference

The debug simple tag sends diagnostic information to the web console during template rendering. Use it to inspect variable values, object structure, and rendering state while developing.

This is StoreConnect’s own developer console, not the browser’s. The output never appears on the page and never reaches the visitor’s browser: it is collected during the render and pushed over a websocket to the console session watching that store.

Nothing is recorded unless a console session is already open, so on an ordinary page render the tag does nothing at all. If a debug tag appears to produce no output, the usual reason is that the console was opened after the page was loaded rather than before.

:::warning Remove debug tags before shipping templates to production. They do not affect page rendering, and outside a console session they do no work, but they are noise for the next person reading the template. :::

Syntax

```liquid

{% debug product_id: product.id, count: items.size %} ```

Property	Value
Tag Name	debug
Type	Simple tag
Source	StoreConnect
Output	The web console only, never the page or the browser’s console

Parameters

The tag accepts zero or more named parameters, separated by commas. Each parameter becomes a key-value pair logged to the console.

Parameter	Type	Description
<name>	Any	A variable or Liquid expression to log. Output format: <name>: <value>

Pass variables or expressions directly. The tag serializes them to the console. You can pass: - Scalar values: debug count: items.size - Objects: debug product: product - Arrays: debug items: cart.items - Complex expressions: debug calculated: (price \| times: quantity)

Description

The debug tag sends output to the web console, not to the page. Each call records a line. Named parameters appear as name: value pairs on a single line.

Viewing debug output

1. Open the web console for the store. Access is controlled by Store Roles, so your user needs one that grants it.
2. Wait for the console to report Connected.
3. In the same browser profile, load the page whose template you are debugging.
4. Find that request in the console. Entries with a debug call are marked with a blue dot, and the Debug entries filter narrows the list to just those.

The console must be connected before you load the page. A request made while it is closed records nothing, and reloading afterwards will not bring it back.

When debug output does not appear

Two situations produce no console entry and no error at all, so the tag looks broken while the console is working normally. Liquid errors from the same template still appear in both cases, so working errors are not evidence that the tag itself is reaching the console. Rule these out before treating the console as the problem.

The tag sits in a controller block that never ran. A {% before %} or {% final %} block only runs inside a controller template whose key matches controllers/<controller>/<action> exactly, and whose controller and action pair is a registered route. Anywhere else, including a page body, a snippet, or a layout, the block body is skipped and the tag inside it never runs. Nothing is logged and nothing is raised. Move the tag outside the block to confirm the template renders at all. See the Liquid controllers guide for the phases and where each one belongs.

The tag sits in a cached fragment that hit. A {% debug %} inside a cache block runs only when the cache misses. On a hit the body is never evaluated, so the tag produces nothing on that request and every request after it. Change the cache key or remove the {% cache %} wrapper while you are debugging.

:::note The tag evaluates every argument before it records anything. If one argument fails to resolve, no line is recorded, including the arguments that would have resolved. When a debug call stops producing output after you add a parameter, remove that parameter first. :::

Examples

Log a single value during development

```liquid

{% debug product_id: product.id %} ```

Console output: product_id: "2c9f2a1f"

Inspect object structure

```liquid

{% debug current_customer: current_customer %} ```

The console shows the full customer object and its properties, so you can see what fields are available and their values.

Log multiple values to debug a calculation

```liquid

{% if (product.price | times: quantity) > 100 %} {% debug product_price: product.price, qty: quantity, total: (product.price | times: quantity) %} High-value item {% endif %} ```

Console output: product_price: 150, qty: 2, total: 300

Inspect array contents while looping

```liquid

{% for item in cart.items %} {% debug item_name: item.product.name, qty: item.quantity %} {% endfor %} ```

The console logs a line for each item, showing what the loop is processing.

Best practices and cautions

• Use sparingly during development. Console output can grow quickly in large loops. Target specific problem areas.
• Be careful logging full objects in development. The console channel is keyed on the user and the store, so in production a message reaches only the staff user watching that store. In development both ids can be blank. That collapses the channel to one shared by every user and store, so anything logged there is visible to anyone else with a console open.
• What not to log: Avoid passing current_customer, current_account, current_cart (full objects), payment details, authentication tokens, or any PII.
• Safe to log: Field values, product IDs, pricing amounts, item counts, boolean flags, feature states.
• Remove before commit. Use your code editor’s Find function to search for debug tags and remove them before merging theme changes.
• A forgotten tag is invisible to customers. It clutters the web console for whoever is watching, and does nothing at all when no one is, but a visitor never sees it, on the page or anywhere else.