{"record":{"id":"587d7887203f47f5","repo":"apache/druid","slug":"frametoolarge","errorCode":"FrameTooLarge","errorMessage":"FrameRowTooLargeException: row too large for frame allocator capacity %s","messagePattern":"FrameRowTooLargeException: row too large for frame allocator capacity (.+?)","errorType":"error_code","errorClass":"FrameRowTooLargeException","httpStatus":null,"severity":"error","filePath":"multi-stage-query/src/main/java/org/apache/druid/msq/querykit/WindowOperatorQueryFrameProcessor.java","lineNumber":265,"sourceCode":"   * @throws IOException\n   */\n  public void writeRacToFrame(RowsAndColumns rac) throws IOException\n  {\n    final int numRows = rac.numRows();\n    while (rowId.get() < numRows) {\n      if (frameWriter.addSelection()) {\n        incrementBoostColumn();\n        rowId.incrementAndGet();\n      } else if (frameWriter.getNumRows() > 0) {\n        flushFrameWriter();\n        createFrameWriterIfNeeded(rac);\n\n        if (frameWriter.addSelection()) {\n          incrementBoostColumn();\n          rowId.incrementAndGet();\n          return;\n        } else {\n          throw new FrameRowTooLargeException(frameWriterFactory.allocatorCapacity());\n        }\n      } else {\n        throw new FrameRowTooLargeException(frameWriterFactory.allocatorCapacity());\n      }\n    }\n\n    flushFrameWriter();\n    clearRACBuffers();\n  }\n\n  @Override\n  public void cleanup() throws IOException\n  {\n    FrameProcessors.closeAll(inputChannels(), outputChannels(), frameWriter);\n  }\n\n  /**\n   * @return Number of rows flushed to the output channel","sourceCodeStart":247,"sourceCodeEnd":283,"githubUrl":"https://github.com/apache/druid/blob/9b90983fd291f26935af934383ce360473179e4d/multi-stage-query/src/main/java/org/apache/druid/msq/querykit/WindowOperatorQueryFrameProcessor.java#L247-L283","documentation":"During window-function processing, writeRacToFrame attempts to append a row to the current frame writer and the frame's allocator has no room left even after the frame was (or could not be) flushed. A single row does not fit within the frame allocator capacity, so processing aborts with a FrameRowTooLargeException mapped to the FrameTooLarge fault code. This means an individual row (not the whole window) exceeds the memory budget allocated per frame.","triggerScenarios":"A window-function stage writes a row whose serialized size exceeds frameWriterFactory.allocatorCapacity(); occurs when frameWriter.addSelection() returns false both after flushing and when the frame is empty (single row larger than capacity).","commonSituations":"Queries with very wide rows (many/large string columns), huge ARRAY/COMPLEX values, or maxRowsMaterialized/worker memory configured so the per-frame allocator capacity is smaller than one row; often after increasing row width via window function output columns.","solutions":["Increase the MSQ frame allocator capacity (e.g. druid.msq.window.frame.size / frame-allocator memory limits in task properties)","Reduce row width: select only needed columns, truncate/limit large string or array values before the window operator","Increase worker/task memory (peon memory, task slot sizing) so larger frame capacities are allowed","Split the query so window functions operate on fewer/narrower columns"],"exampleFix":"// before (task context)\n{\"maxRowsInMemory\": 1000000, \"druid.msq.window.frame.size\": \"256MiB\"}\n// after\n{\"druid.msq.window.frame.size\": \"1GiB\"}","handlingStrategy":"validation","validationCode":"// Estimate row size before window stage; ensure it fits frame capacity\nlong estimatedRowBytes = columns.stream().mapToLong(c -> c.estimatedMaxSize()).sum();\nif (estimatedRowBytes >= frameAllocatorCapacityBytes) {\n  throw new IllegalStateException(\"Row size \" + estimatedRowBytes + \" exceeds frame capacity \" + frameAllocatorCapacityBytes);\n}","typeGuard":null,"tryCatchPattern":"try {\n  runMsqQuery(query);\n} catch (MSQException e) {\n  if (e.getFault() instanceof FrameTooLarge) {\n    // increase druid.msq.frame size or narrow projection and retry\n  }\n}","preventionTips":["Keep window-stage projections narrow","Size frame allocator larger than the maximum expected row","Monitor row width growth after schema changes"],"tags":["msq","window-function","memory","frame-allocator"],"backgroundTag":"payload-too-large","analyzedSha":"9b90983fd291f26935af934383ce360473179e4d","analyzedAt":"2026-09-07T13:32:30.957Z","contentChangedAt":"2026-09-07T13:32:30.957Z","schemaVersion":2},"datasetVersion":"2026-09-14T05:17:10.506Z"}