{"record":{"id":"37e55c2b88a57cfe","repo":"apache/cassandra","slug":"failed-to-serialize-partition-key-s-on-table","errorCode":null,"errorMessage":"Failed to serialize partition key '%s' on table '%s' in keyspace '%s'.","messagePattern":"Failed to serialize partition key '(.+?)' on table '(.+?)' in keyspace '(.+?)'\\.","errorType":"exception","errorClass":"PartitionSerializationException","httpStatus":null,"severity":"error","filePath":"src/java/org/apache/cassandra/db/rows/UnfilteredRowIteratorSerializer.java","lineNumber":112,"sourceCode":"    public void serialize(UnfilteredRowIterator iterator, ColumnFilter selection, DataOutputPlus out, int version, int rowEstimate) throws IOException\n    {\n        serialize(iterator, out, version, rowEstimate, MESSAGING, selection);\n    }\n\n    public <P> void serialize(UnfilteredRowIterator iterator, DataOutputPlus out, int version, int rowEstimate, ParameterizedSerializer<P> serializer, P param) throws IOException\n    {\n        SerializationHeader header = new SerializationHeader(false,\n                                                             iterator.metadata(),\n                                                             iterator.columns(),\n                                                             iterator.stats());\n\n        try\n        {\n            serialize(iterator, header, out, version, rowEstimate, serializer, param);\n        }\n        catch (BufferOverflowException boe)\n        {\n            throw new PartitionSerializationException(iterator, boe);\n        }\n    }\n\n    private void serialize(UnfilteredRowIterator iterator, SerializationHeader header, ColumnFilter selection, DataOutputPlus out, int version, int rowEstimate) throws IOException\n    {\n        serialize(iterator, header, out, version, rowEstimate, MESSAGING, selection);\n    }\n\n    // Should only be used for the on-wire format.\n    private <P> void serialize(UnfilteredRowIterator iterator, SerializationHeader header, DataOutputPlus out, int version, int rowEstimate, ParameterizedSerializer<P> serializer, P param) throws IOException\n    {\n        assert !header.isForSSTable();\n\n        ByteBufferUtil.writeWithVIntLength(iterator.partitionKey().getKey(), out);\n        serializeWithoutKey(iterator, header, out, version, rowEstimate, serializer, param);\n    }\n\n    public <P> void serializeWithoutKey(UnfilteredRowIterator iterator, SerializationHeader header, DataOutputPlus out, int version, int rowEstimate, ParameterizedSerializer<P> serializer, P param) throws IOException","sourceCodeStart":94,"sourceCodeEnd":130,"githubUrl":"https://github.com/apache/cassandra/blob/88fd0f6a0eaed8943f05ac9e8f947882b8ddc8f1/src/java/org/apache/cassandra/db/rows/UnfilteredRowIteratorSerializer.java#L94-L130","documentation":"When serializing a partition for the wire (messaging or streaming), UnfilledRowIteratorSerializer wraps BufferOverflowException from the underlying buffer in a PartitionSerializationException that names the partition key, table and keyspace. It means the partition (or a single row within it under the legacy pre-4.0 limit) exceeded the maximum message size allowed by the configured transport settings, so the partition cannot be sent as-is.","triggerScenarios":"Streaming a huge partition larger than the streaming socket/file-transfer buffer limits; sending a partition exceeding internode message size (native_transport / internode max message size in 4.0+); hinted handoff or read-repair of an oversized partition.","commonSituations":"Very wide partitions from unbounded partition keys; transfer of data written by clients that never bound partition size; tuning max_mutation_size / max message size after the data already exists.","solutions":["Reduce partition size: rewrite the oversized partition with a better partition key and re-stream.","Increase the relevant limits (in 4.0+: stream_throughput / internode max message size, max_mutation_size_in_mb consistently below commitlog segment size) and retry.","Use incremental repair/re-stream or rebuild the target node from scratch instead of moving the giant partition.","Split large partitions during migration using a tool like sstablepartitioner before streaming."],"exampleFix":"// before: cassandra.yaml defaults too small for a 1GB partition\n# max_mutation_size_in_mb: 16\n# commitlog_segment_size_in_mb: 32\n// after: raise consistently (4.0+)\nmax_mutation_size_in_mb: 512\ncommitlog_segment_size_in_mb: 1024\ninternode_max_message_size_in_bytes: 536870912 # and re-stream","handlingStrategy":"try-catch","validationCode":"// estimate partition size before streaming\nlong size = estimatedPartitionSize(key); if (size > maxMessageSize) rePartitionOrSplit(key);","typeGuard":null,"tryCatchPattern":"try { serializePartition(iterator, header, out, version); } catch (PartitionSerializationException e) { handleOversizedPartition(e.partitionKey); }","preventionTips":["Design partition keys to bound partition size (monitor partition sizes)","Align max_mutation_size_in_mb with commitlog_segment_size_in_mb and max message sizes","Use partition-splitting tools before large migrations"],"tags":["serialization","streaming","buffer-overflow","large-partition"],"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-14T11:17:12.474Z"}