{"record":{"id":"080e3cf6f403ec25","repo":"alibaba/nacos","slug":"illegal-raft-system-parameters-readonlyoption","errorCode":null,"errorMessage":"Illegal Raft system parameters => ReadOnlyOption : [{val}], should be 'ReadOnlySafe' or 'ReadOnlyLeaseBased'","messagePattern":"Illegal Raft system parameters => ReadOnlyOption : \\[(.+?)\\], should be 'ReadOnlySafe' or 'ReadOnlyLeaseBased'","errorType":"validation","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"core/src/main/java/com/alibaba/nacos/core/distributed/raft/utils/RaftOptionsBuilder.java","lineNumber":132,"sourceCode":"                DEFAULT_ENABLE_LOG_ENTRY_CHECKSUM));\n        \n        return raftOptions;\n    }\n    \n    private static ReadOnlyOption raftReadIndexType(RaftConfig config) {\n        String readOnySafe = \"ReadOnlySafe\";\n        String readOnlyLeaseBased = \"ReadOnlyLeaseBased\";\n        \n        String val = config.getVal(RaftSysConstants.RAFT_READ_INDEX_TYPE);\n        \n        if (StringUtils.isBlank(val) || StringUtils.equals(readOnySafe, val)) {\n            return ReadOnlyOption.ReadOnlySafe;\n        }\n        \n        if (StringUtils.equals(readOnlyLeaseBased, val)) {\n            return ReadOnlyOption.ReadOnlyLeaseBased;\n        }\n        throw new IllegalArgumentException(\n            \"Illegal Raft system parameters => ReadOnlyOption\" + \" : [\" + val\n                + \"], should be 'ReadOnlySafe' or 'ReadOnlyLeaseBased'\");\n        \n    }\n    \n}\n","sourceCodeStart":114,"sourceCodeEnd":139,"githubUrl":"https://github.com/alibaba/nacos/blob/9b989acdf181d00898f2e8839257bb2b2a3cefe3/core/src/main/java/com/alibaba/nacos/core/distributed/raft/utils/RaftOptionsBuilder.java#L114-L139","documentation":"Thrown by RaftOptionsBuilder.raftReadIndexType when the configured raft read-index type (nacos raft read option, RaftSysConstants.RAFT_READ_INDEX_TYPE) is neither blank, 'ReadOnlySafe', nor 'ReadOnlyLeaseBased'. It is an IllegalArgumentException raised while building RaftOptions during JRaftServer initialization.","triggerScenarios":"Setting the raft read-index type config property to any value other than the two supported strings (blank defaults to ReadOnlySafe). E.g. configuring 'ReadOnly', 'read_only_safe', or a misspelled value.","commonSituations":"Operator copy-pasting a JRaft option name that Nacos does not accept; case mismatch (the check is case-sensitive); a typo in custom.properties / application.properties for the raft read index type.","solutions":["Set the property to exactly 'ReadOnlySafe' or 'ReadOnlyLeaseBased' (case-sensitive), or remove it to default to ReadOnlySafe.","Double-check spelling and case against the two accepted literals.","If unsure of the trade-offs, leave it unset (ReadOnlySafe is the safe default)."],"exampleFix":"// before\n# custom.properties\nnacos.raft.read_index_type=ReadIndexSafe\n\n// after\nnacos.raft.read_index_type=ReadOnlySafe","handlingStrategy":"validation","validationCode":"Set<String> OK = Set.of(\"ReadOnlySafe\", \"ReadOnlyLeaseBased\");\nString val = config.getVal(RaftSysConstants.RAFT_READ_INDEX_TYPE);\nif (val != null && !val.isBlank() && !OK.contains(val)) {\n    throw new IllegalArgumentException(\"Invalid raft read index type: \" + val);\n}","typeGuard":null,"tryCatchPattern":"try {\n    RaftOptionsBuilder.initRaftOptions(raftConfig);\n} catch (IllegalArgumentException e) {\n    // fix the read_index_type config to ReadOnlySafe/ReadOnlyLeaseBased\n}","preventionTips":["Set the read-index type to exactly 'ReadOnlySafe' or 'ReadOnlyLeaseBased' (case-sensitive).","Leave it unset to accept the ReadOnlySafe default."],"tags":["raft","jraft","configuration","validation","startup","cp-protocol"],"backgroundTag":null,"analyzedSha":"9b989acdf181d00898f2e8839257bb2b2a3cefe3","analyzedAt":"2026-08-14T07:17:31.569Z","schemaVersion":2},"datasetVersion":"2026-08-14T10:17:34.591Z"}