alibaba/Sentinel · error · IllegalArgumentException

Null value

Error message

Null value

What it means

Thrown by ParamFlowRuleUtil.parseItemValue(String, String) when the value string of a hot-parameter flow rule's exclusion item is null. Sentinel parses string-encoded param flow rules (e.g. loaded from properties file, Nacos, Apollo, or ZooKeeper datasources) into typed objects; a rule entry whose value field is absent yields null, and this method refuses it with IllegalArgumentException("Null value"). It never happens for rules built programmatically with non-null values.

Source

Thrown at sentinel-extension/sentinel-parameter-flow-control/src/main/java/com/alibaba/csp/sentinel/slots/block/flow/param/ParamFlowRuleUtil.java:224

            Object value;
            try {
                value = parseItemValue(item.getObject(), item.getClassType());
            } catch (Exception ex) {
                RecordLog.warn("[ParamFlowRuleUtil] Failed to parse value for item: " + item, ex);
                continue;
            }
            if (item.getCount() == null || item.getCount() < 0 || value == null) {
                RecordLog.warn("[ParamFlowRuleUtil] Ignoring invalid exclusion parameter item: " + item);
                continue;
            }
            itemMap.put(value, item.getCount());
        }
        return itemMap;
    }

    static Object parseItemValue(String value, String classType) {
        if (value == null) {
            throw new IllegalArgumentException("Null value");
        }
        if (StringUtil.isBlank(classType)) {
            // If the class type is not provided, then treat it as string.
            return value;
        }
        // Handle primitive type.
        if (int.class.toString().equals(classType) || Integer.class.getName().equals(classType)) {
            return Integer.parseInt(value);
        } else if (boolean.class.toString().equals(classType) || Boolean.class.getName().equals(classType)) {
            return Boolean.parseBoolean(value);
        } else if (long.class.toString().equals(classType) || Long.class.getName().equals(classType)) {
            return Long.parseLong(value);
        } else if (double.class.toString().equals(classType) || Double.class.getName().equals(classType)) {
            return Double.parseDouble(value);
        } else if (float.class.toString().equals(classType) || Float.class.getName().equals(classType)) {
            return Float.parseFloat(value);
        } else if (byte.class.toString().equals(classType) || Byte.class.getName().equals(classType)) {
            return Byte.parseByte(value);

View on GitHub (pinned to a3f40ba8e9)

Solutions

1. Inspect the failing ParamFlowRule configuration and add the missing "value" field to every entry in paramFlowItemList
2. Validate rules before publishing: every paramFlowItem / paramFlowItemList entry must have a non-null value and non-negative count
3. If rules are machine-generated, fix the producer so it never serializes an item without a value
4. Wrap rule loading in a try-catch for IllegalArgumentException so one bad rule does not crash startup; Sentinel already logs and skips invalid items in some paths (RecordLog.warn "Ignoring invalid exclusion parameter item")

Example fix

// before (rule JSON pushed to Nacos)
{"resource":"foo","paramIdx":0,"paramFlowItemList":[{"classType":"int","count":2}]}

// after
{"resource":"foo","paramIdx":0,"paramFlowItemList":[{"classType":"int","count":2,"value":"123"}]}

// before publishing a ParamFlowRule, verify every exclusion item has a value
for (ParamFlowItem item : rule.getParamFlowItemList()) {
    if (item == null || item.getObject() == null && parseableValueMissing(item)) {
        throw new IllegalStateException("paramFlowItem without value for rule " + rule.getResource());
    }
}
// simpler: validate the raw config map/JSON before conversion
jsonItems.forEach(i -> Objects.requireNonNull(i.get("value"), "paramFlowItem.value required"));

try {
    ParamFlowRuleManager.loadRules(rules);
} catch (IllegalArgumentException e) {
    log.warn("Rejected invalid param flow rule config: {}", e.getMessage());
    // keep last-good rules instead of crashing startup
}

When it happens

Trigger: Loading a ParamFlowRule from a dynamic configuration source where paramFlowItemList contains an item with a missing/absent "value" JSON field (e.g. {"classType":"int","count":2} with no "value"), causing fillExceptionFlowProperties/parseItemValue to receive null.

Common situations: Typo or omission of the "value" key in a JSON/YAML param flow rule pushed to Nacos/Apollo; a datasource schema change that drops the value field; manually hand-edited rule files. Note the callers guard item.getCount() and value in parseExclusionItems, but other parseItemValue call sites (fillExceptionFlowProperties for map/object values) pass config data straight through.

Related errors

• Cold factor should be larger than 1
• keys empty or null: ${keys}
• keys empty or null
• Max entry count should be at least 1:
• Invalid second interval (cannot divide by 60):

AI-assisted analysis of alibaba/Sentinel@a3f40ba8e9 (2026-08-14). Data as JSON: /api/errors/18fbbfe2068400d8. Report an issue: GitHub.