How to Use Retool's Debugging Tools

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.

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.

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.

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

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.

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.

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.

1// JS Query with debugging console.log statements
2// Logs appear in both Debug Panel Console tab and browser DevTools
3
4console.log('Starting saveAndRefresh');
5console.log('Selected row:', JSON.stringify(table1.selectedRow.data));
6console.log('Form values:', {
7  title: titleInput.value,
8  status: statusSelect.value,
9});
10
11await updateRecord.trigger();
12console.log('Update result:', updateRecord.data);
13
14if (!updateRecord.data || updateRecord.data.length === 0) {
15  console.error('Update returned no rows — check WHERE clause');
16}