apache/shardingsphere · error · ShardingTableRuleNotFoundException

1

1

Error message

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

What it means

ShardingTableRuleNotFoundException thrown by the DistSQL checker ShardingTableRuleStatementChecker.getShardingTable when a statement (e.g. ALTER SHARDING TABLE RULE, or checks that resolve a single existing rule) references a logic table that is not in the current sharding rule's shardingTables map. Unlike the routing variant, this fires at DistSQL execution time while validating the statement against existing configuration.

Solutions

1. Run SHOW SHARDING TABLE RULES and use the exact configured logic table name (mind case).
2. Create the rule before altering it (CREATE SHARDING TABLE RULE if SHOW lists nothing).
3. In deployment scripts, guard the ALTER with an existence check or use IF EXISTS-style handling where supported.

Example fix

-- before: t_order rule does not exist / name mismatch
ALTER SHARDING TABLE RULE t_Order (...);

-- after: verify then alter the exact name
SHOW SHARDING TABLE RULES;
ALTER SHARDING TABLE RULE t_order (...);

-- Guard deployment scripts
SHOW SHARDING TABLE RULES;  -- confirm t_order exists with exact name/case before ALTER
-- or in code: check rule metadata contains the logic table before issuing ALTER

try {
    executeDistSql("ALTER SHARDING TABLE RULE t_order (...)");
} catch (final ShardingTableRuleNotFoundException ex) {
    // fall back to CREATE SHARDING TABLE RULE for a first-time deployment
}

When it happens

Trigger: Running ALTER SHARDING ... on a table name absent from the current rule; DROP/ALTER on a rule that was already dropped or renamed; case mismatch between the DistSQL table name and the configured logic table.

Common situations: Idempotent deployment scripts that re-run ALTER on possibly-dropped rules; renaming logic tables; environment drift where a rule exists in staging but not production.

Related errors

• 1
• 5
• Either key generator name or algorithm segment must be…
• 0
• 1

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

Appendix: source

Thrown at features/sharding/distsql/handler/src/main/java/org/apache/shardingsphere/sharding/distsql/handler/checker/ShardingTableRuleStatementChecker.java:270

            while (iterator.hasNext()) {
                ShardingTable shardingTable = getShardingTable(iterator.next(), shardingTables);
                if (!isValidActualDataSourceName(sampleShardingTable, shardingTable) || !isValidActualTableName(sampleShardingTable, shardingTable)) {
                    return false;
                }
                if (isInvalidShardingAlgorithm(sampleShardingTable, shardingTable, true, checkedConfig) || isInvalidShardingAlgorithm(sampleShardingTable, shardingTable, false, checkedConfig)) {
                    return false;
                }
            }
        }
        return true;
    }
    
    private static ShardingTable getShardingTable(final String logicTableName, final Map<String, ShardingTable> shardingTables) {
        ShardingTable result = shardingTables.get(logicTableName);
        if (null != result) {
            return result;
        }
        throw new ShardingTableRuleNotFoundException(Collections.singleton(logicTableName));
    }
    
    private static boolean isValidActualDataSourceName(final ShardingTable sampleShardingTable, final ShardingTable shardingTable) {
        return sampleShardingTable.getActualDataSourceNames().equals(shardingTable.getActualDataSourceNames());
    }
    
    private static boolean isValidActualTableName(final ShardingTable sampleShardingTable, final ShardingTable shardingTable) {
        for (String each : sampleShardingTable.getActualDataSourceNames()) {
            Collection<String> sampleActualTableNames =
                    sampleShardingTable.getActualTableNames(each).stream().map(actualTableName -> actualTableName.replace(sampleShardingTable.getTableDataNode().getPrefix(), ""))
                            .collect(Collectors.toSet());
            Collection<String> actualTableNames =
                    shardingTable.getActualTableNames(each).stream().map(optional -> optional.replace(shardingTable.getTableDataNode().getPrefix(), "")).collect(Collectors.toSet());
            if (!sampleActualTableNames.equals(actualTableNames)) {
                return false;
            }
        }
        return true;

View on GitHub (pinned to e952770a21)