apache/cassandra · warning

Maximum number of memory map areas per process…

Error message

Maximum number of memory map areas per process (vm.max_map_count) {} is too low, recommended value: {}, you can change it with sysctl.

What it means

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.

Solutions

1. Raise the kernel limit: sysctl -w vm.max_map_count=1048575 and persist it in /etc/sysctl.conf or /etc/sysctl.d/
2. In containerized/Kubernetes environments, set the sysctl at the node level or via securityContext sysctls
3. Alternatively, set disk_access_mode: standard and index_access_mode: standard in cassandra.yaml to bypass mmap (at a read-performance cost)
4. Restart Cassandra and confirm the warning is gone

Example fix

// before (host with default limit)
$ sysctl vm.max_map_count
vm.max_map_count = 65536

// after
$ echo 'vm.max_map_count = 1048575' | sudo tee /etc/sysctl.d/99-cassandra.conf
$ sudo sysctl --system

long maxMapCount = getMaxMapCountFromProc(); // parse /proc/sys/vm/max_map_count
if (maxMapCount < 1048575) {
    throw new IllegalStateException("vm.max_map_count=" + maxMapCount + " too low for mmap; run: sysctl -w vm.max_map_count=1048575");
}

When it happens

Trigger: 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.

Common situations: 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.

Understand the failure class

Background: "value must be between 0 and 1" / "out of range" / "must not be negative" errors: fixing range-validation failures across open-source libraries — this error's family across 42 libraries.

Related errors

• Can not initialize CMS without any seeds
• Cannot find configured row cache provider class
• Cannot locate . If this is a local file, please confirm…
• Cannot replace a live node...
• Cannot replace same address when accord transactions are…

AI-assisted analysis of apache/cassandra@88fd0f6a0e (2026-09-10). Data as JSON: /api/errors/5602e6715f9333c3. Report an issue: GitHub.

Appendix: source

Thrown at src/java/org/apache/cassandra/service/StartupChecks.java:825

            {
                logger.warn("IO exception while reading file {}.", path, e);
            }
            return -1;
        }

        @Override
        public void execute(StartupChecksConfiguration configuration)
        {
            if (configuration.isDisabled(name()) || !FBUtilities.isLinux)
                return;

            if (DatabaseDescriptor.getDiskAccessMode() == Config.DiskAccessMode.standard &&
                DatabaseDescriptor.getIndexAccessMode() == Config.DiskAccessMode.standard)
                return; // no need to check if disk access mode is only standard and not mmap

            long maxMapCount = getMaxMapCount();
            if (maxMapCount < EXPECTED_MAX_MAP_COUNT)
                logger.warn("Maximum number of memory map areas per process (vm.max_map_count) {} " +
                            "is too low, recommended value: {}, you can change it with sysctl.",
                            maxMapCount, EXPECTED_MAX_MAP_COUNT);
        }
    };

    public static final StartupCheck checkDataDirs = new StartupCheck()
    {
        @Override
        public String name()
        {
            return "data_dirs";
        }

        @Override
        public void execute(StartupChecksConfiguration configuration) throws StartupException
        {
            if (configuration.isDisabled(name()))
                return;

View on GitHub (pinned to 88fd0f6a0e)