alibaba/nacos · error · IllegalArgumentException

Illegal Raft system parameters => ReadOnlyOption : [{val}],

Error message

Illegal Raft system parameters => ReadOnlyOption : [{val}], should be 'ReadOnlySafe' or 'ReadOnlyLeaseBased'

What it means

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.

Source

Thrown at core/src/main/java/com/alibaba/nacos/core/distributed/raft/utils/RaftOptionsBuilder.java:132

                DEFAULT_ENABLE_LOG_ENTRY_CHECKSUM));
        
        return raftOptions;
    }
    
    private static ReadOnlyOption raftReadIndexType(RaftConfig config) {
        String readOnySafe = "ReadOnlySafe";
        String readOnlyLeaseBased = "ReadOnlyLeaseBased";
        
        String val = config.getVal(RaftSysConstants.RAFT_READ_INDEX_TYPE);
        
        if (StringUtils.isBlank(val) || StringUtils.equals(readOnySafe, val)) {
            return ReadOnlyOption.ReadOnlySafe;
        }
        
        if (StringUtils.equals(readOnlyLeaseBased, val)) {
            return ReadOnlyOption.ReadOnlyLeaseBased;
        }
        throw new IllegalArgumentException(
            "Illegal Raft system parameters => ReadOnlyOption" + " : [" + val
                + "], should be 'ReadOnlySafe' or 'ReadOnlyLeaseBased'");
        
    }
    
}

View on GitHub (pinned to 9b989acdf1)

Solutions

1. Set the property to exactly 'ReadOnlySafe' or 'ReadOnlyLeaseBased' (case-sensitive), or remove it to default to ReadOnlySafe.
2. Double-check spelling and case against the two accepted literals.
3. If unsure of the trade-offs, leave it unset (ReadOnlySafe is the safe default).

Example fix

// before
# custom.properties
nacos.raft.read_index_type=ReadIndexSafe

// after
nacos.raft.read_index_type=ReadOnlySafe

Set<String> OK = Set.of("ReadOnlySafe", "ReadOnlyLeaseBased");
String val = config.getVal(RaftSysConstants.RAFT_READ_INDEX_TYPE);
if (val != null && !val.isBlank() && !OK.contains(val)) {
    throw new IllegalArgumentException("Invalid raft read index type: " + val);
}

try {
    RaftOptionsBuilder.initRaftOptions(raftConfig);
} catch (IllegalArgumentException e) {
    // fix the read_index_type config to ReadOnlySafe/ReadOnlyLeaseBased
}

When it happens

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

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

Related errors

• Fail to init [BaseRpcServer].
• Failed to install JRaft authentication interceptor
• [http-client] invalid connect timeout:{}
• worker Id can't be greater than %d or less than 0, current w
• serverList is empty,please check configuration

AI-assisted analysis of alibaba/nacos@9b989acdf1 (2026-08-14). Data as JSON: /api/errors/080e3cf6f403ec25. Report an issue: GitHub.