query_memory_limit_exceeded

err:user:unprocessable_entity:query_memory_limit_exceeded

Example

{
  "meta": {
    "requestId": "req_4dgzrNP3Je5mU1tD"
  },
  "error": {
    "detail": "Query result exceeds the maximum response size.",
    "status": 422,
    "title": "Unprocessable Entity",
    "type": "https://unkey.com/docs/errors/user/unprocessable_entity/query_memory_limit_exceeded"
  }
}

What happened?

Your query exceeded its workspace memory quota or produced an encoded response larger than 4 MiB. Unkey limits both values to prevent one analytics query from exhausting shared resources. The response limit applies to the encoded JSON size, not only the number of rows. A query can exceed it with one large aggregate value, many projected columns, or many rows.

How to fix it

1. Return fewer columns and values

Select only the columns you need. Avoid aggregates such as groupArray that can place an unbounded amount of data into one result value.

2. Use aggregations instead of raw data

Instead of fetching all rows, aggregate the data:

SELECT *
FROM key_verifications_v1
WHERE time >= now() - INTERVAL 7 DAY

SELECT
  toStartOfHour(time) as hour,
  key_space_id,
  COUNT(*) as total
FROM key_verifications_v1
WHERE time >= now() - INTERVAL 7 DAY
GROUP BY hour, key_space_id

3. Add more filters

Reduce the amount of data the query needs to process:

SELECT key_space_id, key_id, outcome, time
FROM key_verifications_v1
WHERE time >= now() - INTERVAL 30 DAY

SELECT key_space_id, key_id, outcome, time
FROM key_verifications_v1
WHERE time >= now() - INTERVAL 1 DAY
  AND key_space_id = 'ks_1234'
  AND outcome = 'VALID'

4. Limit result size

Add a LIMIT to cap the number of returned rows. If the response still exceeds 4 MiB, lower the limit or select fewer columns.

SELECT key_space_id, key_id, outcome, time
FROM key_verifications_v1
WHERE time >= now() - INTERVAL 7 DAY
ORDER BY time DESC
LIMIT 10000

5. Avoid large GROUP BY cardinality

GROUP BY on high-cardinality columns (like key_id) uses a lot of memory. Instead, group by lower-cardinality columns:

SELECT key_id, COUNT(*) as total
FROM key_verifications_v1
WHERE time >= now() - INTERVAL 30 DAY
GROUP BY key_id

SELECT outcome, COUNT(*) as total
FROM key_verifications_v1
WHERE time >= now() - INTERVAL 30 DAY
GROUP BY outcome

Need a higher memory quota?

Contact support if your query has a legitimate need for a higher workspace memory quota. The 4 MiB encoded-response limit is fixed, so larger result sets must be split into multiple queries.Reach out to support and tell us:

What you’re trying to analyze
Why the query needs a higher memory quota
An example of the query you’re running

Unkey support can review your use case and determine whether a higher workspace memory quota is appropriate.

Getting Started

Platform

Build & Deploy

Networking

Observability

CLI

Security

Keyspaces

AI Code Gen

Audit Logs

CLI

Errors

query_memory_limit_exceeded

What happened?

How to fix it

1. Return fewer columns and values

2. Use aggregations instead of raw data

3. Add more filters

4. Limit result size

5. Avoid large GROUP BY cardinality

Need a higher memory quota?

​What happened?

​How to fix it

​1. Return fewer columns and values

​2. Use aggregations instead of raw data

​3. Add more filters

​4. Limit result size

​5. Avoid large GROUP BY cardinality

​Need a higher memory quota?

What happened?

How to fix it

1. Return fewer columns and values

2. Use aggregations instead of raw data

3. Add more filters

4. Limit result size

5. Avoid large GROUP BY cardinality

Need a higher memory quota?