apache/shardingsphere · error · IllegalArgumentException

Can not find YAML rule configuration with type: %s

Error message

Can not find YAML rule configuration with type: %s

What it means

Thrown by YamlRuleConfigurationReflectionEngine.findClass when no YamlRuleConfigurationSwapper on the service-loading path has a RuleNodeTupleEntity annotation whose value equals the requested rule type. The engine discovers YAML rule configuration classes by scanning swappers via ShardingSphereServiceLoader and reading their generic parameter's annotation; no match means the rule type is unknown to this installation.

Source

Thrown at mode/node/src/main/java/org/apache/shardingsphere/mode/node/rule/tuple/YamlRuleConfigurationReflectionEngine.java:58

public final class YamlRuleConfigurationReflectionEngine {
    
    /**
     * Find YAML rule configuration class.
     *
     * @param ruleType rule type
     * @return found class
     * @throws IllegalArgumentException throw if YAML rule configuration class not found
     */
    @SuppressWarnings("rawtypes")
    public static Class<? extends YamlRuleConfiguration> findClass(final String ruleType) {
        for (YamlRuleConfigurationSwapper each : ShardingSphereServiceLoader.getServiceInstances(YamlRuleConfigurationSwapper.class)) {
            Class<? extends YamlRuleConfiguration> yamlRuleConfigClass = getYamlRuleConfigurationClass(each);
            RuleNodeTupleEntity entity = yamlRuleConfigClass.getAnnotation(RuleNodeTupleEntity.class);
            if (null != entity && entity.value().equals(ruleType)) {
                return yamlRuleConfigClass;
            }
        }
        throw new IllegalArgumentException(String.format("Can not find YAML rule configuration with type: %s", ruleType));
    }
    
    @SuppressWarnings({"unchecked", "rawtypes"})
    private static Class<? extends YamlRuleConfiguration> getYamlRuleConfigurationClass(final YamlRuleConfigurationSwapper swapper) {
        return (Class<? extends YamlRuleConfiguration>) ((ParameterizedType) swapper.getClass().getGenericInterfaces()[0]).getActualTypeArguments()[0];
    }
    
    /**
     * Get YAML rule configuration fields.
     *
     * @param yamlRuleConfigClass YAML rule configuration class
     * @return got fields
     */
    public static Collection<Field> getFields(final Class<? extends YamlRuleConfiguration> yamlRuleConfigClass) {
        return Arrays.stream(yamlRuleConfigClass.getDeclaredFields())
                .filter(each -> null != each.getAnnotation(RuleNodeTupleField.class))
                .sorted(Comparator.comparingInt(o -> o.getAnnotation(RuleNodeTupleField.class).type().ordinal())).collect(Collectors.toList());
    }

View on GitHub (pinned to e952770a21)

Solutions

1. Verify the rule type string exactly matches the @RuleNodeTupleEntity value of an available swapper implementation.
2. Ensure the module providing the YamlRuleConfigurationSwapper (and its META-INF/services entry) is on the classpath of the process doing the reflection.
3. For custom rules, annotate the YAML configuration class with @RuleNodeTupleEntity and register the swapper via ShardingSphereServiceLoader.

boolean known = ShardingSphereServiceLoader.getServiceInstances(YamlRuleConfigurationSwapper.class).stream()
    .map(YamlRuleConfigurationReflectionEngine::getYamlRuleConfigurationClass)
    .map(c -> c.getAnnotation(RuleNodeTupleEntity.class))
    .anyMatch(a -> null != a && a.value().equals(ruleType));

try {
    Class<? extends YamlRuleConfiguration> clazz = YamlRuleConfigurationReflectionEngine.findClass(ruleType);
} catch (final IllegalArgumentException ex) {
    // rule type has no swapper: check spelling, classpath, SPI registration
}

When it happens

Trigger: Rule-persist/reflection code asking for a rule type string (e.g. from a governance node path) that has no swapper: typos ('sharding' vs 'shardings'), custom rule types whose swapper JAR is missing from the classpath, or a rule introduced in a newer version than the deployed one.

Common situations: Custom or third-party rule SPI implementations without a META-INF/services registration, partial upgrades where the node content contains a newer rule type than the runtime understands, or a renamed rule tuple value across versions.

Related errors

• SPI:1
• This SPI implementation does not support the use of this met
• SPI:1
• Build data consistency checker is not supported.
• Unknown stream channel type `%s`.

AI-assisted analysis of apache/shardingsphere@e952770a21 (2026-08-14). Data as JSON: /api/errors/bfb6614e4172bc2a. Report an issue: GitHub.