# How to Debug Performance Issues in Retool Apps

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

## TL;DR

To debug Retool performance: open Debug Panel → Performance tab → read grades for Payload Size, Component Count, and Query Count. Click 'C' or 'D' grade items to see specific recommendations. Switch to Queries tab to see per-query timing and payload size. The browser Network tab shows database vs network latency split. Fix the lowest-grade issue first — payload is usually the highest impact.

## A Systematic Approach to Retool Performance Investigation

Performance debugging is different from bug debugging — there's rarely a single error message pointing to the cause. Instead, you measure and compare: how long does each query take? How much data is it returning? How many queries are running simultaneously on page load?

This tutorial gives you a systematic investigation process for Retool performance issues, starting with the Debug Panel Performance tab grades, then drilling into specific queries with the Queries tab, and finally using browser DevTools for network-level analysis when needed.

## Before you start

- A Retool app that users have reported as slow or that you've observed taking more than 3 seconds to load
- Access to the Retool Debug Panel and browser DevTools
- Basic understanding of the difference between query execution time and network latency

## Step-by-step guide

### 1. Establish a baseline with the Performance tab

Open your app in edit mode. Open the Debug Panel (bug icon). Navigate to the Performance tab. Read each grade section. Note: Payload Size grade (A=all queries under 1.6MB, F=one or more queries dramatically over), Component Count grade (A=under 30 components, F=50+ components), and Query Count grade (A=few queries on page load, D/F=many queries on page load). Write down the grade for each category — this is your baseline before making any changes.

**Expected result:** Written list of Performance grades with specific issues cited under each failing grade.

### 2. Identify slow queries in the Queries waterfall

Switch to the Queries tab. Reload the app to capture a fresh execution trace. The Queries tab shows all queries that ran during page load, with their duration in milliseconds. Identify queries taking over 300ms — click on each to see their payload size. Queries over 1.6MB payload are immediately flagged with a warning. Note which queries ran on page load (they appear in the first few seconds after reload) vs which are triggered by user interaction.

**Expected result:** Ranked list of queries by duration. Queries over 300ms are identified as optimization candidates.

### 3. Check query payload sizes

For each slow query in the Queries tab, click to expand it. Look for the 'Response size' or payload size information. If a query returns many rows, check: How many rows does it need to return? Are there unnecessary columns in the SELECT? Is there a LIMIT clause? A 1,000-row query with 20 columns generates more data than a 10,000-row query with 2 columns — column count matters as much as row count for payload size.

```
// Checklist for each large-payload query:
// 1. Count columns: SELECT * returns everything vs SELECT id, name, status returns 3
// 2. Check row count: is there a WHERE clause and LIMIT?
// 3. Check for large text/JSON columns: description TEXT can be kilobytes per row
// 4. Check for binary data: image Base64 in SQL results balloons payload

// Example: calculate approximate payload size
// 1000 rows × 5 columns × avg 50 bytes/value ≈ 250KB (fine)
// 1000 rows × 40 columns × avg 200 bytes/value ≈ 8MB (problem)
```

**Expected result:** Root cause of large payload identified (too many columns, rows, or large text fields).

### 4. Investigate unnecessary page-load queries

In the Queries tab, look at which queries fire within the first 2 seconds after page load. These are your page-load queries. Count them. For each one, ask: Is this query needed for the initial view, or only when the user interacts? For queries only needed on user interaction (e.g., a detail query for a modal, a search query), disable 'Run on page load' in the query settings. This reduces simultaneous database load and speeds up initial render.

**Expected result:** List of queries that can have 'Run on page load' disabled. Estimated improvement in page load time.

### 5. Use network waterfall to separate database vs network latency

Open Chrome DevTools Network tab. Filter for 'api/v2/queries'. Reload the app. The network waterfall shows each query as a horizontal bar split into: waiting (time in queue), TTFB (time to first byte — includes Retool routing + database execution), and download (response payload download). If TTFB is 2 seconds but download is 100ms, the bottleneck is the database query execution. If TTFB is 100ms but download is 2 seconds, the bottleneck is payload size. This split tells you whether to optimize SQL or reduce payload.

**Expected result:** Network waterfall reveals whether the bottleneck is in database execution (TTFB) or data transfer (download).

### 6. Create a performance fix priority list

Combine the Debug Panel Performance grades and Queries tab timing into a fix priority list. Order fixes by: (1) Payload grade F — immediate payload reduction needed, (2) Query grade D/F — too many page-load queries, disable unnecessary ones, (3) Slow individual queries (>500ms) — SQL optimization or caching, (4) Component count grade — split into multipage app. Implement one fix at a time and re-check grades after each change to measure improvement.

**Expected result:** Prioritized action plan with expected performance improvement for each fix.

## Complete code example

File: `Performance investigation checklist`

```javascript
// RETOOL PERFORMANCE INVESTIGATION CHECKLIST
// Work through each item in order — fix the highest impact issues first

/*
STEP 1: Debug Panel → Performance tab grades
[ ] Payload Size grade: ___ (target: A or B)
[ ] Component Count grade: ___ (target: A or B, reduce if >40)
[ ] Query Count grade: ___ (target: A, reduce page-load queries)

STEP 2: Queries tab — identify slow/large queries
For each query taking >300ms:
[ ] Query name: _____________
[ ] Duration: ___ms
[ ] Payload size: ___KB/MB
[ ] Fix: [ ] Add LIMIT  [ ] Remove columns  [ ] Add WHERE  [ ] Add caching

STEP 3: Page-load query audit
For each query running on page load:
[ ] Is it needed for the initial view? Y/N
[ ] If N: disable 'Run on page load'
Queries to disable: _______________

STEP 4: Network tab waterfall
[ ] TTFB > 1s for slow queries → database bottleneck → SQL optimization
[ ] Download > 1s → payload bottleneck → reduce SELECT columns / add LIMIT

STEP 5: Estimated improvements
[ ] After payload reduction: expected load time reduction ___ms
[ ] After disabling N page-load queries: expected parallel load reduction
[ ] After caching: expected reduction in database calls per hour
*/
```

## Common mistakes

- **Trying to fix all performance grades simultaneously without measuring after each change** — undefined Fix: Fix one issue, reload the app, check the Debug Panel grades again. Systematic one-at-a-time changes give you clear causation data and prevent over-engineering.
- **Focusing on component count optimization when payload size is the actual bottleneck** — undefined Fix: Payload size typically has 10x more impact on load time than component count. Always fix F-grade payload issues before spending time reducing component count.
- **Testing performance in the Retool editor instead of the published app** — undefined Fix: The editor loads additional framework code for the editing experience. Published app performance is typically faster. Test final performance in a published or preview app, not the edit mode.

## Best practices

- Always measure baseline performance before making changes — you need numbers to confirm improvements
- Fix one issue at a time and re-measure — stacking changes without measuring makes it impossible to know what helped
- The Performance tab grades are heuristics, not hard rules — a B-grade payload may still be acceptable for your use case
- Profile your app with a cold cache (first load) and warm cache separately — they have different optimization strategies
- Test performance with realistic data volumes — a query that performs fine with 100 rows may be a problem with 10,000
- Involve your database admin for SQL-level optimizations — Retool developers often aren't database performance experts

## Frequently asked questions

### What is a 'good' page load time target for Retool apps?

Retool recommends targeting under 3 seconds for initial page load (from navigation to all above-the-fold content). Under 2 seconds is excellent. Over 5 seconds will generate user complaints. These targets are for the published app; the editor loads slower due to the editing framework.

### Why does my Retool app load fast for me but slowly for other users?

Your computer may have cached data from the Retool editor session. Test from an incognito window or a different device to get an accurate cold-load time. Also consider geographic location — users far from your Retool data center or database may experience higher network latency.

### Does the number of hidden components affect Retool app performance?

Yes — components with Hidden set to true are still rendered in the DOM but invisible. They consume memory and contribute to the Performance tab component count grade. For components that are frequently hidden, consider removing them entirely and dynamically adding them (via modal or conditional rendering) rather than permanently hiding them.

---

Source: https://www.rapidevelopers.com/retool-tutorial/how-to-debug-performance-issues-in-retool-apps
© RapidDev — https://www.rapidevelopers.com/retool-tutorial/how-to-debug-performance-issues-in-retool-apps