# How to Use Retool's Debugging Tools

- Tool: Retool
- Difficulty: Advanced
- Time required: 20-25 min
- Compatibility: Retool Cloud and Self-hosted
- Last updated: March 2026

## TL;DR

Open Retool's Debug Panel by clicking the bug icon (bottom-left of the editor). The Queries tab shows query execution timing and payloads. The State tab shows all component values in real time. The Performance tab grades your app A-F on payload size, component count, and query count. The Console tab shows console.log output from JS Queries.

## The Debug Panel: Your Primary Debugging Interface in Retool

The Retool Debug Panel is the first place to go when something isn't working in your app. It provides four distinct views: the Queries tab shows what queries ran (and when), the State tab shows the current value of every component property, the Performance tab identifies optimization opportunities, and the Console tab displays JavaScript logs.

Most Retool debugging issues can be resolved without ever opening the browser DevTools, just using the Debug Panel. This tutorial walks through each tab systematically and shows how to use them to diagnose real-world issues.

## Before you start

- A Retool app in edit mode (the Debug Panel is only available in the editor)
- Basic familiarity with the Retool editor interface
- At least one query and a few components in your app

## Step-by-step guide

### 1. Open the Debug Panel

In the Retool editor, click the bug icon in the bottom-left corner of the screen (it looks like a beetle/bug icon). The Debug Panel slides up from the bottom of the screen. It has four tabs at the top: Queries, State, Performance, and Console. You can resize the panel by dragging the divider between it and the canvas. Press Escape or click the bug icon again to close it.

**Expected result:** Debug Panel opens at the bottom of the Retool editor.

### 2. Use the Queries tab to trace query execution

The Queries tab shows a chronological list of all queries that have run since the page loaded. Each entry shows: query name, status (green check for success, red X for error), execution duration in milliseconds, and payload size in bytes. Click on any query to expand it and see the full request (SQL/config + parameters) and response (returned data or error message). For queries with errors, the error message appears in red under the query name.

**Expected result:** Queries tab lists all executed queries with timing, status, and expandable request/response details.

### 3. Diagnose query failures in the Queries tab

When a query shows a red error status, click to expand it. The error message shows what went wrong: 'relation does not exist' (wrong table name), 'permission denied' (RLS or user permissions issue), 'syntax error at or near' (SQL syntax error), '401 Unauthorized' (API authentication failure), or 'ETIMEDOUT' (database connection timeout). Look at the 'Params' section to see the actual parameter values that were passed — often the issue is a null or undefined value being passed where a real value was expected.

```
// Common query errors and their meanings:
// 'relation "orders" does not exist' → wrong table name or wrong database
// 'permission denied for table orders' → RLS policy blocking the query
// 'invalid input syntax for type integer: ""' → empty string where number expected
//   Fix: {{ textInput1.value || null }} instead of {{ textInput1.value }}
// 'JWT expired' → OAuth token needs refresh
// 'column "orderId" does not exist' → wrong column name casing
```

**Expected result:** Root cause of query failure identified from the error message and parameter values.

### 4. Use the State tab to inspect component values

The State tab shows a tree of all components in your app with their current property values. Expand any component to see its properties: a Table shows selectedRow, data, pageIndex, pageSize. A Text Input shows value and defaultValue. A Temporary State shows its current value. This is invaluable for debugging: if a query is returning unexpected results, check the State tab to see what values are actually being passed as parameters by looking at the input components referenced in the query.

**Expected result:** State tab shows live values of all component properties. You can identify mismatched or null values causing query failures.

### 5. Read the Performance tab grades

The Performance tab grades your app from A to F in several categories: Payload Size (total data returned by all queries), Component Count (number of components in the app), Query Count (number of queries running on page load), and potentially others based on your Retool version. Each grade has a brief explanation and specific recommendations. An 'F' on Payload Size might say 'query1 returns 2.1MB — exceeds 1.6MB limit'. Follow the specific recommendation for each failing grade.

**Expected result:** Performance grades with specific improvement recommendations for each failing grade.

### 6. Use the Console tab for JS Query debugging

When you add console.log() calls in your JS Queries, the output appears in the Debug Panel Console tab (not just the browser DevTools console). This makes it easy to debug query logic without switching to DevTools. Add console.log statements at key points in your JS Queries to trace execution flow and inspect variable values. The Console tab also shows console.error() output in red.

```
// JS Query with debugging console.log statements
// Logs appear in both Debug Panel Console tab and browser DevTools

console.log('Starting saveAndRefresh');
console.log('Selected row:', JSON.stringify(table1.selectedRow.data));
console.log('Form values:', {
  title: titleInput.value,
  status: statusSelect.value,
});

await updateRecord.trigger();
console.log('Update result:', updateRecord.data);

if (!updateRecord.data || updateRecord.data.length === 0) {
  console.error('Update returned no rows — check WHERE clause');
}
```

**Expected result:** console.log output from JS Queries appears in the Debug Panel Console tab during development.

## Complete code example

File: `JS Query: debugStateInspector`

```javascript
// JS Query: debugStateInspector
// A debugging utility that logs the current state of
// all key components to the Debug Panel Console tab
// Remove or disable this before publishing to production

const debugInfo = {
  // Query states
  queries: {
    query1_status: typeof query1 !== 'undefined' ? {
      isFetching: query1.isFetching,
      data_length: query1.data?.length,
      error: query1.error,
      lastRun: query1.metadata?.lastSuccessfulRunAt,
    } : 'undefined',
  },

  // Component values
  components: {
    table1_selectedRow: table1.selectedRow?.data,
    table1_pageIndex: table1.pageIndex,
    textInput1_value: typeof textInput1 !== 'undefined' ? textInput1.value : 'undefined',
    select1_value: typeof select1 !== 'undefined' ? select1.value : 'undefined',
  },

  // Temporary state
  state: {
    isSubmitting: typeof isSubmitting !== 'undefined' ? isSubmitting.value : 'undefined',
    currentLang: typeof currentLang !== 'undefined' ? currentLang.value : 'undefined',
  },
};

console.log('[DEBUG STATE]', JSON.stringify(debugInfo, null, 2));

return debugInfo;
```

## Common mistakes

- **Opening browser DevTools first when the Retool Debug Panel would have shown the issue faster** — undefined Fix: Start debugging with the Debug Panel. The Queries tab shows query errors directly. The State tab shows component values. Only move to browser DevTools for issues the Debug Panel doesn't surface (CSS problems, browser-level errors, network inspection for non-Retool requests).
- **Leaving console.log statements in production JS Queries** — undefined Fix: Console.log output is visible to end users in browser DevTools and may expose sensitive data (query parameters, user info). Remove or comment out debug logs before publishing apps.
- **Not checking the State tab when a query has unexpected results, assuming the SQL is wrong** — undefined Fix: Before editing the SQL, use the State tab to verify that the component values referenced in the query are what you expect. A query filtering by {{ textInput1.value }} may return wrong results simply because textInput1.value is empty string or undefined.

## Best practices

- Always check the Debug Panel before the browser DevTools — the Debug Panel gives Retool-specific context that DevTools doesn't
- Use the State tab to verify parameter values before debugging the SQL — 90% of query failures are caused by null/undefined parameters
- Add targeted console.log statements in JS Queries rather than debugging blindly
- Remove or disable debug console.log statements before publishing an app to end users
- Use the Performance tab grades as a quality gate before releasing significant app updates
- For production issues, reproduce in edit mode to access the Debug Panel — the Debug Panel is only available in the editor

## Frequently asked questions

### Is the Retool Debug Panel available in published apps (not just the editor)?

The Debug Panel is only available in the Retool editor (edit mode). Published apps do not show the Debug Panel to end users. To debug a production issue, open the app in edit mode from the Retool home page and reproduce the issue there to access the Debug Panel.

### Why does the Debug Panel Queries tab show queries in a different order than I expected?

The Queries tab shows queries in execution order — the order they actually ran, not the order they appear in your query list. Queries with 'Run on page load' enabled all fire simultaneously and appear in the order their responses arrive. The chronological order in the Queries tab reflects actual network timing.

### Can I export or share Debug Panel data for collaborative debugging?

The Debug Panel does not have an export or share feature. For collaborative debugging, take screenshots of the Queries tab (especially the error detail and Params), copy-paste the State tab values you need to share, and use console.log to write diagnostic data to the browser console which can be exported via DevTools.

---

Source: https://www.rapidevelopers.com/retool-tutorial/how-to-use-retool-s-debugging-tools
© RapidDev — https://www.rapidevelopers.com/retool-tutorial/how-to-use-retool-s-debugging-tools