{"record":{"id":"2d876b923b6fb1cb","repo":"apache/cassandra","slug":"cassandra-server-running-in-degraded-mode","errorCode":null,"errorMessage":"Cassandra server running in degraded mode. ","messagePattern":"Cassandra server running in degraded mode\\. ","errorType":"console","errorClass":null,"httpStatus":null,"severity":"warning","filePath":"src/java/org/apache/cassandra/service/StartupChecks.java","lineNumber":685,"sourceCode":"                throw new StartupException(StartupException.ERR_WRONG_MACHINE_STATE, \"The native library could not be initialized properly. \");\n        }\n    };\n\n    public static final StartupCheck checkProcessEnvironment = new StartupCheck()\n    {\n        @Override\n        public String name()\n        {\n            return \"process_environment\";\n        }\n\n        @Override\n        public void execute(StartupChecksConfiguration configuration)\n        {\n            Optional<String> degradations = FBUtilities.getSystemInfo().isDegraded();\n\n            if (degradations.isPresent())\n                logger.warn(\"Cassandra server running in degraded mode. \" + degradations.get());\n            else\n                logger.info(\"Checked OS settings and found them configured for optimal performance.\");\n        }\n    };\n\n    public static final StartupCheck checkReadAheadKbSetting = new StartupCheck()\n    {\n        @Override\n        public String name()\n        {\n            return \"read_ahead_kb_setting\";\n        }\n\n        // This value is in KB.\n        private static final long MAX_RECOMMENDED_READ_AHEAD_KB_SETTING = 128;\n\n        /**\n         * Function to get the block device system path(Example: /dev/sda) from the","sourceCodeStart":667,"sourceCodeEnd":703,"githubUrl":"https://github.com/apache/cassandra/blob/88fd0f6a0eaed8943f05ac9e8f947882b8ddc8f1/src/java/org/apache/cassandra/service/StartupChecks.java#L667-L703","documentation":"The checkSystemCheck startup check inspects OS-level settings via FBUtilities.getSystemInfo().isDegraded(). When the host's kernel settings are below Cassandra's recommendations (e.g. vm.max_map_count, fs.file-max, somaxconn, swappiness-related knobs exposed by SystemInfo), it logs a warning listing the degradations; otherwise it logs an informational 'optimal performance' message. Startup continues either way.","triggerScenarios":"Starting Cassandra on a host whose kernel parameters (sysctl) are below required thresholds, so FBUtilities.getSystemInfo().isDegraded() returns a non-empty Optional.","commonSituations":"Bare-metal hosts or containers where sysctls were never tuned, Kubernetes pods with restricted /proc/sys, shared hosts where another admin lowered limits, fresh VM images without cassandra sysctl tuning.","solutions":["Read the appended degradation detail in the log line; it names each failing setting.","Apply the recommended sysctl values in /etc/sysctl.d/ (e.g. vm.max_map_count=1048575, fs.file-max, net.core.somaxconn) and re-run sysctl --system.","In containers, set the sysctls in the container runtime/Kubernetes securityContext (where allowed) or on the host.","Re-start Cassandra and confirm the 'Checked OS settings and found them configured for optimal performance.' info message."],"exampleFix":"# before\ncat /proc/sys/vm/max_map_count  -> 65530\n# after\necho 'vm.max_map_count=1048575' > /etc/sysctl.d/99-cassandra.conf && sysctl --system","handlingStrategy":"validation","validationCode":"#!/bin/sh\n# prestart sysctl guard\nfor kv in \"vm.max_map_count:1048575\" \"fs.file-max:100000\" \"net.core.somaxconn:4096\"; do\n  k=${kv%%:*}; need=${kv##*:}; have=$(cat /proc/sys/$k 2>/dev/null || echo 0);\n  [ \"$have\" -ge \"$need\" ] || echo \"DEGRADED: $k=$have (want >= $need)\";\ndone","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Ship a sysctl.d file (e.g. /etc/sysctl.d/99-cassandra.conf) with every node image.","In Kubernetes, set allowed sysctls via securityContext.sysctls or tune the host.","Re-run `sysctl --system` after OS updates (updates can reset values).","Read the degradation detail in the log line — it lists exactly which settings fail."],"tags":["os","sysctl","startup-check","performance"],"backgroundTag":"invalid-config-value","analyzedSha":"88fd0f6a0eaed8943f05ac9e8f947882b8ddc8f1","analyzedAt":"2026-09-10T07:29:22.284Z","contentChangedAt":"2026-09-10T07:29:22.284Z","schemaVersion":2},"datasetVersion":"2026-09-14T16:17:12.679Z"}