{"record":{"id":"b69c98ddd18aa054","repo":"alibaba/spring-cloud-alibaba","slug":"sentinel-starter-datasource-datasourcename-han","errorCode":null,"errorMessage":"[Sentinel Starter] DataSource {dataSourceName} handle {classSimpleName} error, class name: {converterClass}","messagePattern":"\\[Sentinel Starter\\] DataSource (.+?) handle (.+?) error, class name: (.+?)","errorType":"exception","errorClass":"RuntimeException","httpStatus":null,"severity":"error","filePath":"spring-cloud-alibaba-starters/spring-cloud-starter-alibaba-sentinel/src/main/java/com/alibaba/cloud/sentinel/custom/SentinelDataSourceHandler.java","lineNumber":170,"sourceCode":"\t\t\t\t\t\tString customConvertBeanName = \"sentinel-\"\n\t\t\t\t\t\t\t\t+ dataSourceProperties.getConverterClass();\n\t\t\t\t\t\tif (!this.beanFactory.containsBean(customConvertBeanName)) {\n\t\t\t\t\t\t\tthis.beanFactory.registerBeanDefinition(customConvertBeanName,\n\t\t\t\t\t\t\t\t\tBeanDefinitionBuilder\n\t\t\t\t\t\t\t\t\t\t\t.genericBeanDefinition(\n\t\t\t\t\t\t\t\t\t\t\t\t\tClass.forName(dataSourceProperties\n\t\t\t\t\t\t\t\t\t\t\t\t\t\t\t.getConverterClass()))\n\t\t\t\t\t\t\t\t\t\t\t.getBeanDefinition());\n\t\t\t\t\t\t}\n\t\t\t\t\t\tbuilder.addPropertyReference(\"converter\", customConvertBeanName);\n\t\t\t\t\t}\n\t\t\t\t\tcatch (ClassNotFoundException e) {\n\t\t\t\t\t\tlog.error(\"[Sentinel Starter] DataSource \" + dataSourceName\n\t\t\t\t\t\t\t\t+ \" handle \"\n\t\t\t\t\t\t\t\t+ dataSourceProperties.getClass().getSimpleName()\n\t\t\t\t\t\t\t\t+ \" error, class name: \"\n\t\t\t\t\t\t\t\t+ dataSourceProperties.getConverterClass());\n\t\t\t\t\t\tthrow new RuntimeException(\"[Sentinel Starter] DataSource \"\n\t\t\t\t\t\t\t\t+ dataSourceName + \" handle \"\n\t\t\t\t\t\t\t\t+ dataSourceProperties.getClass().getSimpleName()\n\t\t\t\t\t\t\t\t+ \" error, class name: \"\n\t\t\t\t\t\t\t\t+ dataSourceProperties.getConverterClass(), e);\n\t\t\t\t\t}\n\t\t\t\t}\n\t\t\t\telse {\n\t\t\t\t\tif (!dataTypeList.contains(\n\t\t\t\t\t\t\tStringUtils.trimAllWhitespace(propertyValue.toString()))) {\n\t\t\t\t\t\tthrow new RuntimeException(\"[Sentinel Starter] DataSource \"\n\t\t\t\t\t\t\t\t+ dataSourceName + \" dataType: \" + propertyValue\n\t\t\t\t\t\t\t\t+ \" is not support now. please using these types: \"\n\t\t\t\t\t\t\t\t+ dataTypeList.toString());\n\t\t\t\t\t}\n\t\t\t\t\t// converter type now support xml or json.\n\t\t\t\t\t// The bean name of these converters wrapped by\n\t\t\t\t\t// 'sentinel-{converterType}-{ruleType}-converter'\n\t\t\t\t\tif (dataSourceProperties.getRuleType() != null) {","sourceCodeStart":152,"sourceCodeEnd":188,"githubUrl":"https://github.com/alibaba/spring-cloud-alibaba/blob/115d5901102009492e05d5ec18c3f79cad4077d0/spring-cloud-alibaba-starters/spring-cloud-starter-alibaba-sentinel/src/main/java/com/alibaba/cloud/sentinel/custom/SentinelDataSourceHandler.java#L152-L188","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Correct the converter-class fully-qualified name to match the actual class location.","Add the missing artifact containing the converter class to your dependencies.","If using a shade/relocate plugin, update the configured FQN to the relocated name.","Ensure the class implements com.alibaba.csp.sentinel.datasource.Converter."],"exampleFix":"# before\nspring.cloud.sentinel.datasource.ds1.converter-class=com.example.OldConverter\n# after\nspring.cloud.sentinel.datasource.ds1.converter-class=com.example.rules.MyRuleConverter","handlingStrategy":"try-catch","validationCode":"void requireConverterOnClasspath(String fqn) throws ClassNotFoundException {\n  Class.forName(fqn, false, getClass().getClassLoader());\n}","typeGuard":null,"tryCatchPattern":"try { Class.forName(converterClass); }\ncatch (ClassNotFoundException e) { log.error(\"converter-class {} missing from classpath\", converterClass); throw e; }","preventionTips":["Verify converter-class FQN against the actual class location.","Add the converter's artifact as a dependency.","Account for shade-plugin relocations when configuring the FQN."],"tags":["sentinel","datasource","classpath","converter"],"backgroundTag":null,"analyzedSha":"115d5901102009492e05d5ec18c3f79cad4077d0","analyzedAt":"2026-08-14T04:47:13.900Z","schemaVersion":2},"datasetVersion":"2026-08-14T05:17:29.042Z"}