---
title: Troubleshooting guide
description: Troubleshoot common R2 SQL errors including query structure, type, and timeout issues.
image: https://developers.cloudflare.com/dev-products-preview.png
---

> Documentation Index  
> Fetch the complete documentation index at: https://developers.cloudflare.com/r2-sql/llms.txt  
> Use this file to discover all available pages before exploring further.

[Skip to content](#%5Ftop) 

### Tags

[ SQL ](https://developers.cloudflare.com/search/?tags=SQL) 

# Troubleshooting guide

This guide covers potential errors and limitations you may encounter when using R2 SQL. R2 SQL is in open beta, and supported functionality will evolve and change over time.

## Query structure errors

### Missing required clauses

**Error**: `expected exactly 1 table in FROM clause`

**Problem**: R2 SQL requires a `FROM` clause in your query.

```

-- Invalid - Missing FROM clause

SELECT user_id WHERE status = 200;


-- Valid

SELECT user_id

FROM my_namespace.http_requests

WHERE status = 200 AND timestamp BETWEEN '2025-09-24T01:00:00Z' AND '2025-09-25T01:00:00Z';


```

**Solution**: Always include `FROM` with a fully qualified table name (`namespace_name.table_name`).

---

## FROM clause issues

### Multiple tables

**Error**: `unsupported feature: JOIN operations are not supported`

**Problem**: R2 SQL queries reference exactly one table. JOINs and multiple tables are not supported.

```

-- Invalid - Multiple tables not supported

SELECT a.*, b.* FROM my_namespace.table1 a, my_namespace.table2 b WHERE a.id = b.id

SELECT * FROM my_namespace.events JOIN my_namespace.users ON events.user_id = users.id


-- Valid - Separate queries

SELECT * FROM my_namespace.table1 WHERE id IN ('id1', 'id2', 'id3') LIMIT 100

-- Then query the second table separately in your application

SELECT * FROM my_namespace.table2 WHERE id IN ('id1', 'id2', 'id3') LIMIT 100


```

**Solution**:

* Denormalize your data by including necessary fields in a single table.
* Perform multiple queries and join data in your application.

### Subqueries

**Error**: `unsupported feature: subqueries`

**Problem**: Subqueries in `FROM`, `WHERE`, and scalar positions are not supported.

```

-- Invalid - Subqueries not supported

SELECT * FROM (SELECT user_id FROM my_namespace.events WHERE status = 200)


-- Valid - Use direct query with appropriate filters

SELECT user_id FROM my_namespace.events WHERE status = 200 LIMIT 100


```

**Solution**: Flatten your query logic or use multiple sequential queries.

---

## WHERE clause issues

### JSON object filtering

**Error**: `unsupported binary operator` or `Error during planning: could not parse compound`

**Problem**: JSON functions are not yet implemented. You cannot filter on fields inside JSON objects using JSON path operators.

```

-- Invalid - JSON path operators not supported

SELECT * FROM my_namespace.requests WHERE json_data->>'level' = 'error'


-- Valid - Filter on the entire JSON column

SELECT * FROM my_namespace.logs WHERE json_data IS NOT NULL LIMIT 100


```

**Solution**:

* Denormalize frequently queried JSON fields into separate columns.
* Filter on the entire JSON field, and handle parsing in your application.

Note

Struct columns are supported and can be filtered using bracket notation. Refer to [Complex types](https://developers.cloudflare.com/r2-sql/sql-reference/complex-types/) for details.

```

SELECT * FROM my_namespace.products WHERE pricing['price'] > 50 LIMIT 100


```

---

## LIMIT clause issues

### Invalid limit values

**Error**: `maximum LIMIT is 10000`

**Problem**: LIMIT values must be between 1 and 10,000.

```

-- Invalid - Out of range

SELECT * FROM my_namespace.events LIMIT 50000


-- Valid

SELECT * FROM my_namespace.events LIMIT 10000


```

**Solution**: Use LIMIT values between 1 and 10,000.

### Pagination attempts

**Error**: `unsupported feature: OFFSET clause is not supported`

**Problem**: OFFSET is not supported.

```

-- Invalid - Pagination not supported

SELECT * FROM my_namespace.events LIMIT 100 OFFSET 200


-- Valid - Use cursor-based pagination with ORDER BY and WHERE

-- Page 1

SELECT * FROM my_namespace.events

WHERE timestamp >= '2024-01-01'

ORDER BY timestamp

LIMIT 100


-- Page 2 - Use the last timestamp from the previous page

SELECT * FROM my_namespace.events

WHERE timestamp > '2024-01-01T10:30:00Z'

ORDER BY timestamp

LIMIT 100


```

**Solution**: Implement cursor-based pagination using `ORDER BY` and `WHERE` conditions.

---

## Schema issues

### DDL and DML operations

**Error**: `only read-only queries are allowed`

**Problem**: R2 SQL is a read-only query engine. DDL and DML statements are not supported.

```

-- Invalid - Schema changes not supported

ALTER TABLE my_namespace.events ADD COLUMN new_field STRING

UPDATE my_namespace.events SET status = 200 WHERE user_id = '123'

CREATE TABLE my_namespace.test (id INT)

DROP TABLE my_namespace.events


```

**Solution**: Manage your schema through your data ingestion pipeline and R2 Data Catalog.

---

## Performance optimization

### Query performance issues

If your queries are running slowly:

1. **Always include partition (timestamp) filters**: This is the most important optimization.  
```  
-- Good - Narrows data scan to one day  
SELECT * FROM my_namespace.events  
WHERE timestamp BETWEEN '2024-01-01' AND '2024-01-02'  
LIMIT 100  
```
2. **Use selective filtering**: Include specific conditions to reduce result sets.  
```  
-- Good - Multiple filters reduce scanned data  
SELECT * FROM my_namespace.events  
WHERE status = 200 AND region = 'US' AND timestamp > '2024-01-01'  
LIMIT 100  
```
3. **Select specific columns**: Avoid `SELECT *` when you only need a few fields.  
```  
-- Good - Only reads the columns you need  
SELECT user_id, status, timestamp  
FROM my_namespace.events  
WHERE timestamp > '2024-01-01'  
LIMIT 100  
```
4. **Use EXPLAIN to inspect the execution plan**: Verify that predicate pushdown and file pruning are working.  
```  
EXPLAIN SELECT user_id, status  
FROM my_namespace.events  
WHERE timestamp > '2024-01-01' AND status = 200  
```
5. **Enable compaction**: Enable compaction in R2 Data Catalog to reduce the number of small files scanned per query.

```json
{"@context":"https://schema.org","@type":"BreadcrumbList","itemListElement":[{"@type":"ListItem","position":1,"item":{"@id":"/directory/","name":"Directory"}},{"@type":"ListItem","position":2,"item":{"@id":"/r2-sql/","name":"R2 SQL"}},{"@type":"ListItem","position":3,"item":{"@id":"/r2-sql/troubleshooting/","name":"Troubleshooting guide"}}]}
```