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.