{"record":{"id":"c5a9f89bd32d7ff7","repo":"apache/cassandra","slug":"max-value-size-must-be-smaller-than-2048-but-was","errorCode":null,"errorMessage":"max_value_size must be smaller than 2048, but was <value>","messagePattern":"max_value_size must be smaller than 2048, but was <value>","errorType":"validation","errorClass":"ConfigurationException","httpStatus":null,"severity":"error","filePath":"src/java/org/apache/cassandra/config/DatabaseDescriptor.java","lineNumber":1175,"sourceCode":"            conf.jmx_server_options = JMXServerOptions.createParsingSystemProperties();\n        }\n        else if (JMXServerOptions.isEnabledBySystemProperties())\n        {\n                throw new ConfigurationException(\"Configure either jmx_server_options in cassandra.yaml and comment out \" +\n                                                 \"configure_jmx function call in cassandra-env.sh or keep cassandra-env.sh \" +\n                                                 \"to call configure_jmx function but you have to keep jmx_server_options \" +\n                                                 \"in cassandra.yaml commented out.\");\n        }\n\n        conf.jmx_server_options.jmx_encryption_options.applyConfig();\n\n        if (conf.snapshot_links_per_second < 0)\n            throw new ConfigurationException(\"snapshot_links_per_second must be >= 0\");\n\n        if (conf.max_value_size.toMebibytes() == 0)\n            throw new ConfigurationException(\"max_value_size must be positive\", false);\n        else if (conf.max_value_size.toMebibytes() >= 2048)\n            throw new ConfigurationException(\"max_value_size must be smaller than 2048, but was \"\n                                             + conf.max_value_size.toString(), false);\n\n        switch (conf.disk_optimization_strategy)\n        {\n            case ssd:\n                diskOptimizationStrategy = new SsdDiskOptimizationStrategy(conf.disk_optimization_page_cross_chance);\n                break;\n            case spinning:\n                diskOptimizationStrategy = new SpinningDiskOptimizationStrategy();\n                break;\n        }\n\n        if (conf.compressed_read_ahead_buffer_size.toKibibytes() > 0 && conf.compressed_read_ahead_buffer_size.toKibibytes() < 256)\n            throw new ConfigurationException(\"compressed_read_ahead_buffer_size must be at least 256KiB (set to 0 to disable), but was \" + conf.compressed_read_ahead_buffer_size, false);\n\n        if (conf.server_encryption_options != null)\n        {\n            conf.server_encryption_options.applyConfig();","sourceCodeStart":1157,"sourceCodeEnd":1193,"githubUrl":"https://github.com/apache/cassandra/blob/88fd0f6a0eaed8943f05ac9e8f947882b8ddc8f1/src/java/org/apache/cassandra/config/DatabaseDescriptor.java#L1157-L1193","documentation":"max_value_size must stay below 2048 MiB because values are read through a bounded buffer whose addressing is limited to 2GB. DatabaseDescriptor throws this ConfigurationException, including the offending value in the message, when max_value_size.toMebibytes() >= 2048.","triggerScenarios":"cassandra.yaml sets max_value_size_in_bytes (or max_value_size) to 2048 MiB or more (e.g. 2147483648 bytes or '2g' or larger) and DatabaseDescriptor.applySimpleConfig runs at startup.","commonSituations":"Operators trying to admit huge blobs by setting 2g/4g; misunderstanding that 2048 is exclusive so the max allowed is just under 2048 MiB; copy-paste of max_message_size-like values into max_value_size.","solutions":["Set max_value_size_in_bytes to less than 2147483648 bytes (e.g. 2097152000 for ~2000 MiB)","Split oversized payloads into multiple values or use external blob storage with references","Remove the override to use the default"],"exampleFix":"# before (cassandra.yaml)\nmax_value_size_in_bytes: 2147483648\n# after\nmax_value_size_in_bytes: 2097152000","handlingStrategy":"validation","validationCode":"if (conf.max_value_size.toMebibytes() >= 2048) throw new IllegalArgumentException(\"max_value_size must be < 2048 MiB\");","typeGuard":null,"tryCatchPattern":"try { DatabaseDescriptor.applyConfig(conf); } catch (ConfigurationException e) { if (e.getMessage().contains(\"smaller than 2048\")) { /* clamp value below 2GiB */ } }","preventionTips":["Treat 2048 MiB as an exclusive upper bound (max allowed is 2047 MiB)","Do not copy internode message-size values into max_value_size","Use external blob storage instead of trying to raise limits beyond 2GiB"],"tags":["cassandra","configuration","limits"],"backgroundTag":"value-out-of-range","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"}