# How to Debug Network Requests in Retool

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

## TL;DR

To debug Retool network requests, open Chrome DevTools (F12) → Network tab, filter by 'api/v2/queries' to see Retool query requests. Each query execution appears as a POST request. Expand any request to see the query body (SQL, headers) and response (data or error). A 401 means authentication failure in the resource config. A 500 usually means a query execution error.

## When to Use Browser DevTools vs the Retool Debug Panel

The Retool Debug Panel is the primary debugging tool for most issues. But some problems require going deeper into the browser's network layer: when you suspect a resource configuration problem, when queries are hitting CORS errors, when Retool's own API is returning unexpected responses, or when you need to see raw HTTP request/response data that the Debug Panel summarizes.

This tutorial covers network debugging specifically: how to find Retool's API calls in DevTools, how to read query request/response pairs, and how to diagnose the most common network-level errors.

## Before you start

- Chrome or Firefox browser with DevTools available (F12 or Cmd+Option+I)
- A Retool app that is experiencing query failures or unexpected results
- Basic familiarity with HTTP status codes (200, 401, 403, 500)

## Step-by-step guide

### 1. Open DevTools Network tab and filter for Retool API requests

Open Chrome DevTools with F12 (Windows/Linux) or Cmd+Option+I (Mac). Click the 'Network' tab. In the filter box, type 'queries/run' or 'api/v2' to filter for Retool's query execution API calls. Clear the network log (click the no-entry icon) and then trigger a query in your app. A POST request will appear in the network log for each query execution. If you don't see requests after filtering, try clearing the filter and looking for XHR requests to your Retool domain.

**Expected result:** Network tab shows Retool API requests for query execution after filtering.

### 2. Inspect a query request

Click on a query request in the network log to expand it. Navigate to the 'Payload' or 'Request' tab to see what was sent to Retool's API: the query type (postgresql, restapi, etc.), the resolved SQL or API configuration, and the parameter values. This shows you the exact query that Retool executed, with all {{ }} expressions already resolved to their final values. Compare the parameters here to what you expected — null values in params are often the root cause of 'query returns no rows'.

**Expected result:** Request payload shows the exact query configuration and resolved parameter values sent to the database.

### 3. Read the response to diagnose errors

Click the 'Response' or 'Preview' tab in the expanded network request to see what came back. A successful query response has status 200 and contains the query result data. Common error responses: 401 (authentication failure — resource credentials are wrong or expired), 403 (authorization error — user doesn't have permission), 422 (validation error — query parameters are invalid), 500 (server error — the query executed but an error occurred on the database or API).

```
// Common Retool API HTTP status codes and meanings:

// 200 OK — Query executed successfully
// 400 Bad Request — Invalid query configuration
// 401 Unauthorized — Resource credentials invalid (expired OAuth, wrong API key)
// 403 Forbidden — User doesn't have permission to run this query
// 422 Unprocessable Entity — Query parameters failed validation
// 429 Too Many Requests — Rate limit hit on external API
// 500 Internal Server Error — Error on database or API side
// 503 Service Unavailable — Retool backend or your database is down
// 504 Gateway Timeout — Query took too long (>30s default timeout)
```

**Expected result:** HTTP status code and error message in response identify the category of failure.

### 4. Diagnose 401 Unauthorized errors

A 401 error on a Retool query request means the resource credentials are invalid or expired. Steps to fix: (1) Go to Settings → Resources and open the failing resource. (2) Test the connection — click 'Test connection' to verify credentials work. (3) For OAuth resources, check if the token has expired and re-authenticate. (4) For API Key resources, verify the key is correct and hasn't been rotated. (5) For database resources, check that the database user's password hasn't changed. The 401 error in the network tab is always a resource configuration problem, not an app code problem.

**Expected result:** Resource configuration issue identified and resolved. Queries return 200 after fixing credentials.

### 5. Identify CORS errors in the Network tab

If a query is using JavaScript's fetch() directly (instead of a Retool resource query), it may hit CORS (Cross-Origin Resource Sharing) errors. In the Network tab, a CORS-blocked request shows as a red request with a CORS error in the console (not a status code — the request is blocked before it reaches the server). The fix: move the API call from a JS fetch() to a Retool REST API resource query. Retool's resource queries proxy through Retool's servers, bypassing browser CORS restrictions.

```
// ❌ This in a JS Query will hit CORS:
const response = await fetch('https://api.external.com/data', {
  headers: { Authorization: 'Bearer token' },
});

// ✅ This in a REST API resource query bypasses CORS:
// Create a 'External API' REST resource pointing to https://api.external.com
// Then query: GET /data with header Authorization: Bearer {{ token }}
// Resource queries run server-side through Retool — no CORS issue
```

**Expected result:** CORS error identified and fixed by moving API call to a Retool REST API resource query.

### 6. Correlate Debug Panel and Network tab for full visibility

Use both tools together for complex debugging: the Debug Panel Queries tab shows query names, status, and Retool-level timing. The Network tab shows the actual HTTP request/response. When the Debug Panel shows a query failed, switch to Network tab to see the HTTP status code and full error response body. The timing in the network tab shows how long Retool spent routing vs how long the database took — useful for diagnosing latency sources.

**Expected result:** Root cause of query failure identified using the combination of Debug Panel error messages and Network tab HTTP details.

## Complete code example

File: `Network request inspection notes`

```javascript
// When inspecting Retool network requests in DevTools,
// here is the structure of what you'll see:

// REQUEST (POST to /api/v2/queries/<queryId>/run):
// Headers:
//   Authorization: Bearer <retool-session-token>
//   Content-Type: application/json
//   X-Retool-Org: your-org
// Body:
//   {
//     queryTableName: 'myDatabaseResource',
//     query: 'SELECT * FROM orders WHERE id = $1',
//     parameters: ['123'],
//     queryType: 'postgresql'
//   }

// RESPONSE (200 OK):
// {
//   success: true,
//   data: [{ id: 123, customer_name: 'Alice', status: 'active' }]
// }

// RESPONSE (500 Error):
// {
//   success: false,
//   error: 'error: relation "orders" does not exist',
//   data: []
// }

// What to look for:
// - parameters: [] → check if {{ }} expressions resolved correctly
// - error: 'permission denied' → RLS or DB user permissions
// - error: 'connection refused' → DB is down or wrong port/host
// - error: 'SSL connection' → SSL config mismatch
```

## Common mistakes

- **Using JavaScript fetch() in JS Queries for external API calls and getting CORS errors** — undefined Fix: Move API calls to Retool REST API resource queries. Resource queries run server-side through Retool's infrastructure, bypassing browser CORS restrictions. Direct fetch() calls from JS Queries run in the browser sandbox and trigger CORS.
- **Seeing a 401 error and assuming it's a user permission issue in Retool** — undefined Fix: A 401 on a query execution request is a resource credential problem, not a Retool user permission problem. Check Settings → Resources → Test connection to verify the resource credentials are valid.
- **Looking for individual SQL queries in the Network tab instead of the Retool API wrapper requests** — undefined Fix: Retool sends SQL to your database through its backend — you won't see raw SQL in the browser Network tab. You'll see POST requests to Retool's /api/v2/queries/ endpoint. The SQL is inside the request body, not a direct database connection.

## Best practices

- Filter the Network tab to '/api/v2/queries' to avoid noise from other Retool framework requests
- Always check the request Payload first when a query returns unexpected results — verify the actual parameters Retool sent
- Use 'Copy as cURL' on a failed request to share it with your team or reproduce it outside Retool
- For rate limit (429) errors from external APIs, add wait logic in JS Queries using setTimeout or implement a retry with backoff
- Differentiate between Retool platform errors (4xx from Retool's API) and resource errors (errors in the response body from your database/API)

## Frequently asked questions

### Can I see the actual SQL being sent to my database in the Network tab?

Yes — in the Network tab, find the POST request to /api/v2/queries/[id]/run, click it, and go to the Payload tab. The request body contains the query SQL template and the resolved parameter values. This shows exactly what Retool sent, which is useful for verifying that {{ }} expressions resolved correctly.

### What does a CORS error look like in the Retool context?

CORS errors appear in the browser DevTools Console as red messages containing 'Access to fetch at... has been blocked by CORS policy'. In the Network tab, the blocked request shows as a red entry without a status code (it was blocked before reaching the server). CORS in Retool almost always means you're using fetch() in a JS Query instead of a REST API resource query.

### How do I find which Retool API request corresponds to which query in my app?

In the Network tab, each query execution request URL contains the query ID (a UUID). To find which query in your app has a given ID, check the Debug Panel Queries tab — it shows query names alongside their execution records. Alternatively, look at the request payload where the queryTableName and queryType fields identify the resource and query type.

---

Source: https://www.rapidevelopers.com/retool-tutorial/how-to-debug-network-requests-in-retool
© RapidDev — https://www.rapidevelopers.com/retool-tutorial/how-to-debug-network-requests-in-retool