{"record":{"id":"d7c0b9b1240787ad","repo":"apache/cassandra","slug":"hint-of-s-bytes-is-too-large-the-maximum-size-i","errorCode":null,"errorMessage":"Hint of %s bytes is too large - the maximum size is %s","messagePattern":"Hint of (.+?) bytes is too large - the maximum size is (.+?)","errorType":"exception","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"src/java/org/apache/cassandra/hints/HintsBuffer.java","lineNumber":154,"sourceCode":"                Integer offset = bufferOffsets.poll();\n\n                if (offset == null)\n                    return endOfData();\n\n                int totalSize = slab.getInt(offset) + ENTRY_OVERHEAD_SIZE;\n\n                return flyweight.clear().position(offset).limit(offset + totalSize);\n            }\n        };\n    }\n\n    Allocation allocate(int hintSize)\n    {\n        int totalSize = hintSize + ENTRY_OVERHEAD_SIZE;\n\n        if (totalSize > slab.capacity() / 2)\n        {\n            throw new IllegalArgumentException(String.format(\"Hint of %s bytes is too large - the maximum size is %s\",\n                                                             hintSize,\n                                                             slab.capacity() / 2));\n        }\n\n        OpOrder.Group opGroup = appendOrder.start(); // will eventually be closed by the receiver of the allocation\n        try\n        {\n            return allocate(totalSize, opGroup);\n        }\n        catch (Throwable t)\n        {\n            opGroup.close();\n            throw t;\n        }\n    }\n\n    private Allocation allocate(int totalSize, OpOrder.Group opGroup)\n    {","sourceCodeStart":136,"sourceCodeEnd":172,"githubUrl":"https://github.com/apache/cassandra/blob/88fd0f6a0eaed8943f05ac9e8f947882b8ddc8f1/src/java/org/apache/cassandra/hints/HintsBuffer.java#L136-L172","documentation":"HintsBuffer.allocate() throws IllegalArgumentException when a hint (plus its per-entry overhead) does not fit within half of the allocated slab capacity. The hints buffer slab has a fixed size, and an incoming hint larger than that threshold can never be buffered, so it is rejected at allocation time rather than corrupting the slab.","triggerScenarios":"Writing a hint whose serialized mutation is larger than the hints buffer slab allows — typically a huge batch mutation, very large partition update, or a row count/size that inflates the hint beyond slab capacity / 2. Reached via HintsService/allocator when buffering hints for a down node.","commonSituations":"Very large batchlog-sized batches applied while a replica is down; max_hinted_handoff or buffer sizes configured small while workloads emit giant mutations; migration from clusters with bigger hints buffers; huge counters or wide partitions exceeding the hint ceiling.","solutions":["Increase max_hinted_handoff / hints buffer configuration so the slab can hold workload-sized hints, or reduce mutation size.","Split very large batches into smaller mutations; Cassandra recommends batches under ~0.5MB anyway.","If the node receiving hints cannot handle the size, let the client retry writes directly to the replica once it returns instead of relying on hinted handoff.","Tune cassandra.yaml hints settings (max_hint_window, hint buffer sizing) consistently across the cluster."],"exampleFix":"// before\n// one huge mutation hinted while replica is down\nsession.execute(veryLargeBatchInsert);\n// after\nfor (List<Statement> chunk : Lists.partition(statements, 100))\n    session.execute(BatchStatement.newInstance(BatchStatement.Type.UNLOGGED, chunk));","handlingStrategy":"try-catch","validationCode":"// reject oversized batches before writing when a replica may be down\nif (estimatedSerializedSize(mutation) > maxHintSize())\n    throw new IllegalArgumentException(\"mutation too large to hint\");","typeGuard":null,"tryCatchPattern":"try { hintsService.write(descriptor, hint); } catch (IllegalArgumentException e) { logger.warn(\"Hint too large for buffer, dropping: {}\", e.getMessage()); }","preventionTips":["Keep batches small (< ~0.5MB, ideally a few dozen rows).","Size hints buffer/max_hinted_handoff relative to your largest expected mutations.","Avoid giant unlogged batches during expected replica downtime; use retries instead.","Monitor hint size metrics and alerts for allocation failures."],"tags":["java","hints","limits","memory"],"backgroundTag":"payload-too-large","analyzedSha":"88fd0f6a0eaed8943f05ac9e8f947882b8ddc8f1","analyzedAt":"2026-09-10T07:29:22.284Z","contentChangedAt":"2026-09-10T07:29:22.284Z","schemaVersion":2},"datasetVersion":"2026-09-17T15:17:12.973Z"}