{"record":{"id":"5602e6715f9333c3","repo":"apache/cassandra","slug":"maximum-number-of-memory-map-areas-per-process-vm","errorCode":null,"errorMessage":"Maximum number of memory map areas per process (vm.max_map_count) {} is too low, recommended value: {}, you can change it with sysctl.","messagePattern":"Maximum number of memory map areas per process \\(vm\\.max_map_count\\) (.+?) is too low, recommended value: (.+?), you can change it with sysctl\\.","errorType":"console","errorClass":null,"httpStatus":null,"severity":"warning","filePath":"src/java/org/apache/cassandra/service/StartupChecks.java","lineNumber":825,"sourceCode":"            {\n                logger.warn(\"IO exception while reading file {}.\", path, e);\n            }\n            return -1;\n        }\n\n        @Override\n        public void execute(StartupChecksConfiguration configuration)\n        {\n            if (configuration.isDisabled(name()) || !FBUtilities.isLinux)\n                return;\n\n            if (DatabaseDescriptor.getDiskAccessMode() == Config.DiskAccessMode.standard &&\n                DatabaseDescriptor.getIndexAccessMode() == Config.DiskAccessMode.standard)\n                return; // no need to check if disk access mode is only standard and not mmap\n\n            long maxMapCount = getMaxMapCount();\n            if (maxMapCount < EXPECTED_MAX_MAP_COUNT)\n                logger.warn(\"Maximum number of memory map areas per process (vm.max_map_count) {} \" +\n                            \"is too low, recommended value: {}, you can change it with sysctl.\",\n                            maxMapCount, EXPECTED_MAX_MAP_COUNT);\n        }\n    };\n\n    public static final StartupCheck checkDataDirs = new StartupCheck()\n    {\n        @Override\n        public String name()\n        {\n            return \"data_dirs\";\n        }\n\n        @Override\n        public void execute(StartupChecksConfiguration configuration) throws StartupException\n        {\n            if (configuration.isDisabled(name()))\n                return;","sourceCodeStart":807,"sourceCodeEnd":843,"githubUrl":"https://github.com/apache/cassandra/blob/88fd0f6a0eaed8943f05ac9e8f947882b8ddc8f1/src/java/org/apache/cassandra/service/StartupChecks.java#L807-L843","documentation":"Cassandra memory-maps SSTable files for fast reads. Each mmap consumes a virtual-memory map area, so the kernel limit vm.max_map_count must be high enough. At startup, if both disk and index access modes are not 'standard', the check reads the kernel limit and warns when it is below the recommended value (EXPECTED_MAX_MAP_COUNT), because low limits cause mmap failures ('too many open files' / map errors) under load.","triggerScenarios":"Node starts with disk_access_mode or index_access_mode set to mmap/auto (the default) while the host kernel's vm.max_map_count sysctl is below the recommended threshold; detected by checkMaxMapCount during startup checks.","commonSituations":"Running Cassandra in containers or on tuned hosts where sysctls were never raised; default Linux vm.max_map_count=65536 with many SSTables; Kubernetes pods without privileged sysctl configuration.","solutions":["Raise the kernel limit: sysctl -w vm.max_map_count=1048575 and persist it in /etc/sysctl.conf or /etc/sysctl.d/","In containerized/Kubernetes environments, set the sysctl at the node level or via securityContext sysctls","Alternatively, set disk_access_mode: standard and index_access_mode: standard in cassandra.yaml to bypass mmap (at a read-performance cost)","Restart Cassandra and confirm the warning is gone"],"exampleFix":"// before (host with default limit)\n$ sysctl vm.max_map_count\nvm.max_map_count = 65536\n\n// after\n$ echo 'vm.max_map_count = 1048575' | sudo tee /etc/sysctl.d/99-cassandra.conf\n$ sudo sysctl --system","handlingStrategy":"validation","validationCode":"long maxMapCount = getMaxMapCountFromProc(); // parse /proc/sys/vm/max_map_count\nif (maxMapCount < 1048575) {\n    throw new IllegalStateException(\"vm.max_map_count=\" + maxMapCount + \" too low for mmap; run: sysctl -w vm.max_map_count=1048575\");\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Bake vm.max_map_count into host/container base images","Verify sysctls in CI before deploying Cassandra","Set explicit disk_access_mode in cassandra.yaml so mmap expectations are intentional"],"tags":["startup","mmap","kernel","linux","configuration"],"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"}