alibaba/spring-cloud-alibaba · error · IllegalArgumentException

sentinel rule convert error: {}

Error message

sentinel rule convert error: {}

What it means

Thrown by SentinelConverter.convert during Sentinel rule deserialization when an individual rule item fails to convert from JSON to the target rule class (FlowRule, DegradeRule, etc.). The outer loop parses a JSON array into List<HashMap>, then each element is serialized back to a JSON string and passed to convertRule which calls objectMapper.readValue(ruleStr, ruleClass). If the individual rule JSON does not match the schema of the target rule class, a JacksonException is caught and re-thrown as IllegalArgumentException with the Jackson error message appended.

Source

Thrown at spring-cloud-alibaba-starters/spring-cloud-alibaba-sentinel-datasource/src/main/java/com/alibaba/cloud/sentinel/datasource/converter/SentinelConverter.java:95

		if (StringUtils.isEmpty(source)) {
			log.info("converter can not convert rules because source is empty");
			return ruleCollection;
		}
		try {
			List sourceArray = objectMapper.readValue(source,
					new TypeReference<List<HashMap>>() {
					});

			for (Object obj : sourceArray) {
				try {
					String item = objectMapper.writeValueAsString(obj);
					Optional.ofNullable(convertRule(item))
							.ifPresent(convertRule -> ruleCollection.add(convertRule));
				}
				catch (JacksonException e) {
					log.error("sentinel rule convert error: " + e.getMessage(), e);
					throw new IllegalArgumentException(
							"sentinel rule convert error: " + e.getMessage(), e);
				}
			}
		}
		catch (Exception e) {
			if (e instanceof RuntimeException runtimeException) {
				throw runtimeException;
			}
			else {
				throw new RuntimeException("convert error: " + e.getMessage(), e);
			}
		}
		return ruleCollection;
	}

	private Object convertRule(String ruleStr) {
		return objectMapper.readValue(ruleStr, ruleClass);
	}

View on GitHub (pinned to 115d590110)

Solutions

1. Inspect the Sentinel rule JSON in your datasource (file, Nacos config, etc.) and validate each element against the expected rule class schema (FlowRule, DegradeRule, SystemRule, AuthorityRule, or ParamFlowRule).
2. Fix the specific rule element that has the type mismatch or invalid field value — the Jackson error message in the exception identifies the field.
3. Ensure the datasource data-type matches the rule content (e.g., spring.cloud.sentinel.datasource.<name>.<type>.data-type=flow for FlowRule JSON).
4. If upgrading Sentinel versions, check the migration guide for rule schema changes.

Example fix

// before (broken — threshold is a string, FlowRule expects double)
[
  {"resource": "hello", "grade": 1, "count": "5"}
]

// after (fixed)
[
  {"resource": "hello", "grade": 1, "count": 5}
]

// Before pushing rules to the datasource, validate each element
// matches the target rule class schema using a test ObjectMapper
ObjectMapper mapper = new ObjectMapper();
try {
    List<Map<String, Object>> rules = mapper.readValue(ruleJson,
        new TypeReference<List<Map<String, Object>>>() {});
    for (Map<String, Object> rule : rules) {
        mapper.readValue(mapper.writeValueAsString(rule), FlowRule.class);
    }
} catch (Exception e) {
    log.error("Rule validation failed: {}", e.getMessage());
}

// Wrap rule loading in a try-catch at the application level
try {
    // load or refresh Sentinel rules from datasource
} catch (IllegalArgumentException e) {
    if (e.getMessage().contains("sentinel rule convert error")) {
        log.error("Sentinel rule conversion failed — check rule JSON format: {}",
            e.getMessage());
        // Do not let bad rules crash the app — log and continue with existing rules
    } else {
        throw e;
    }
}

When it happens

Trigger: A Sentinel datasource (file, Nacos, Apollo, etc.) provides rule data as a JSON array where one or more elements have fields that cannot be deserialized into the configured rule class. For example, a FlowRule JSON with a string value where an integer is expected, an unknown enum value, or a missing required field that the Jackson ObjectMapper rejects in strict mode.

Common situations: 1) Sentinel rule JSON format changed between versions and old rules have deprecated/removed fields. 2) Rule data authored manually with type mismatches (e.g., threshold as string '100' instead of number 100 in strict mode). 3) Wrong data-type configuration: datasource configured as flow-rules but the JSON contains degrade-rule structure. 4) Jackson strict mode rejects extra/unknown fields in the rule JSON.

Related errors

• convert error: {}
• Invalid date format
• [Sentinel Starter] DataSource {dataSourceName}dataType is cu
• [Sentinel Starter] DataSource {dataSourceName} handle {class
• ConsulDataSource server-host is empty

AI-assisted analysis of alibaba/spring-cloud-alibaba@115d590110 (2026-08-14). Data as JSON: /api/errors/6a05cf8726f621df. Report an issue: GitHub.