alibaba/spring-cloud-alibaba · error · RuntimeException

[Sentinel Starter] DataSource {dataSourceName} handle {class

Error message

[Sentinel Starter] DataSource {dataSourceName} handle {classSimpleName} error, class name: {converterClass}

What it means

When data-type is custom and a converter-class is supplied, the framework does Class.forName on it to register a converter bean. If the class cannot be found on the classpath, the ClassNotFoundException is wrapped in this RuntimeException naming the datasource, the properties class simple name, and the missing converter class.

Source

Thrown at spring-cloud-alibaba-starters/spring-cloud-starter-alibaba-sentinel/src/main/java/com/alibaba/cloud/sentinel/custom/SentinelDataSourceHandler.java:170

						String customConvertBeanName = "sentinel-"
								+ dataSourceProperties.getConverterClass();
						if (!this.beanFactory.containsBean(customConvertBeanName)) {
							this.beanFactory.registerBeanDefinition(customConvertBeanName,
									BeanDefinitionBuilder
											.genericBeanDefinition(
													Class.forName(dataSourceProperties
															.getConverterClass()))
											.getBeanDefinition());
						}
						builder.addPropertyReference("converter", customConvertBeanName);
					}
					catch (ClassNotFoundException e) {
						log.error("[Sentinel Starter] DataSource " + dataSourceName
								+ " handle "
								+ dataSourceProperties.getClass().getSimpleName()
								+ " error, class name: "
								+ dataSourceProperties.getConverterClass());
						throw new RuntimeException("[Sentinel Starter] DataSource "
								+ dataSourceName + " handle "
								+ dataSourceProperties.getClass().getSimpleName()
								+ " error, class name: "
								+ dataSourceProperties.getConverterClass(), e);
					}
				}
				else {
					if (!dataTypeList.contains(
							StringUtils.trimAllWhitespace(propertyValue.toString()))) {
						throw new RuntimeException("[Sentinel Starter] DataSource "
								+ dataSourceName + " dataType: " + propertyValue
								+ " is not support now. please using these types: "
								+ dataTypeList.toString());
					}
					// converter type now support xml or json.
					// The bean name of these converters wrapped by
					// 'sentinel-{converterType}-{ruleType}-converter'
					if (dataSourceProperties.getRuleType() != null) {

View on GitHub (pinned to 115d590110)

Solutions

1. Correct the converter-class fully-qualified name to match the actual class location.
2. Add the missing artifact containing the converter class to your dependencies.
3. If using a shade/relocate plugin, update the configured FQN to the relocated name.
4. Ensure the class implements com.alibaba.csp.sentinel.datasource.Converter.

Example fix

# before
spring.cloud.sentinel.datasource.ds1.converter-class=com.example.OldConverter
# after
spring.cloud.sentinel.datasource.ds1.converter-class=com.example.rules.MyRuleConverter

void requireConverterOnClasspath(String fqn) throws ClassNotFoundException {
  Class.forName(fqn, false, getClass().getClassLoader());
}

try { Class.forName(converterClass); }
catch (ClassNotFoundException e) { log.error("converter-class {} missing from classpath", converterClass); throw e; }

When it happens

Trigger: converter-class points to a class not present: a typo in the FQN, a class in a dependency not yet on the classpath, or a class shaded/relocated by a build plugin.

Common situations: Forgetting to add the module that contains the converter. Refactoring/moving the converter class without updating config. Shade plugin relocating the package so the configured FQN no longer matches.

Related errors

• [Sentinel Starter] DataSource {dataSourceName}dataType is cu
• ConsulDataSource server-host is empty
• ConsulDataSource ruleKey can not be empty
• [Sentinel Starter] DataSource {} file cannot be null
• [Sentinel Starter] DataSource {} handle file [{}] error: {}

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