apache/shardingsphere · error · ShardingTableRuleNotFoundException

1

1

Error message

Can not find table rule with logic tables '%s'.

What it means

ShardingTableRuleNotFoundException ('Can not find table rule with logic tables') is thrown by ShardingComplexRouteEngine when none of the logic tables in a multi-table statement matches any sharding table rule: the loop over logicTables finds no shardingTable via shardingRule.findShardingTable, routeContexts stays empty, and the exception lists the logic tables. It means routing reached the complex engine (multiple tables involved) but no rule claims any of them.

Source

Thrown at features/sharding/core/src/main/java/org/apache/shardingsphere/sharding/route/engine/type/complex/ShardingComplexRouteEngine.java:67

    private final ConfigurationProperties props;
    
    private final Collection<String> logicTables;
    
    @Override
    public RouteContext route(final ShardingRule shardingRule) {
        Collection<String> bindingTableNames = new CaseInsensitiveSet<>();
        Collection<RouteContext> routeContexts = new LinkedList<>();
        for (String each : logicTables) {
            Optional<ShardingTable> shardingTable = shardingRule.findShardingTable(each);
            if (shardingTable.isPresent()) {
                if (!bindingTableNames.contains(each)) {
                    routeContexts.add(new ShardingStandardRouteEngine(shardingTable.get().getLogicTable(), shardingConditions, sqlStatementContext, hintValueContext, props).route(shardingRule));
                }
                shardingRule.findBindingTableRule(each).ifPresent(optional -> bindingTableNames.addAll(optional.getShardingTables().keySet()));
            }
        }
        if (routeContexts.isEmpty()) {
            throw new ShardingTableRuleNotFoundException(logicTables);
        }
        RouteContext result = new RouteContext();
        if (1 == routeContexts.size()) {
            RouteContext newRouteContext = routeContexts.iterator().next();
            result.getOriginalDataNodes().addAll(newRouteContext.getOriginalDataNodes());
            result.getRouteUnits().addAll(newRouteContext.getRouteUnits());
        } else {
            RouteContext routeContext = new ShardingCartesianRouteEngine(routeContexts).route(shardingRule);
            result.getOriginalDataNodes().addAll(routeContext.getOriginalDataNodes());
            result.getRouteUnits().addAll(routeContext.getRouteUnits());
        }
        return result;
    }
}

View on GitHub (pinned to e952770a21)

Solutions

1. Add the reported logic table(s) to the sharding rule (tables or autoTables entry) or fix the table name/case in the SQL.
2. If the table is intentionally unsharded, configure a default strategy or move the table into a non-sharded schema/database handled by another rule.
3. After rule changes via DistSQL, confirm the altered rule is complete: ALTER SHARDING TABLE RULE must list all tables; verify with SHOW SHARDING TABLE RULES.

Example fix

-- before: t_inventory missing from rule
SELECT * FROM t_order o JOIN t_inventory i ON o.id=i.order_id;

-- after: add rule for the missing table
ALTER SHARDING TABLE RULE t_inventory (
  DATANODES("ds_${0..1}.t_inventory"),
  SHARDING_COLUMN(warehouse_id), TYPE(NAME=hash_mod, PROPERTIES("sharding-count"=2))
);

// Verify every table referenced by the statement has a rule before executing
Set<String> referenced = Set.of("t_order", "t_inventory");
Set<String> configured = ruleMetaData.getConfiguration().getTables().stream()
        .map(ShardingTableRuleConfiguration::getLogicTable)
        .collect(Collectors.toSet());
referenced.stream().filter(Predicate.not(configured::contains)).findAny()
        .ifPresent(t -> { throw new IllegalStateException("No sharding rule for " + t); });

try {
    rs = stmt.executeQuery(sql);
} catch (final ShardingTableRuleNotFoundException ex) {
    // create the missing rule (or fix table name) then retry
}

When it happens

Trigger: A SQL statement referencing multiple tables that are routed by the complex engine while none of the referenced table names exists in the sharding rule's tables/autoTables configuration (including case mismatches, missing default sharding strategy).

Common situations: Referencing a table not configured in the sharding rule (typo, wrong case on case-sensitive backends, table only present in some environments); removing a rule while the application still queries the table; missing default-database-strategy/table-strategy configuration.

Related errors

• 41
• 57
• 4
• 5
• 1

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