apache/shardingsphere · error · ActualTableNotFoundException

4

4

Error message

Actual table '%s.%s' is not in table rule configuration.

What it means

ActualTableNotFoundException is thrown by BindingTableRule.getBindingActualTable when the 'other' table in a binding group has no actual table at the given data source: otherShardingTable.findActualTableIndex(dataSource, otherActualTable) returns -1 (table absent or otherLogicTable unknown), so the index into the bound table's actual data nodes cannot be computed. It signals that a routed actual table of one binding member does not exist in the configuration of the member being resolved.

Source

Thrown at features/sharding/core/src/main/java/org/apache/shardingsphere/sharding/rule/BindingTableRule.java:67

        return shardingTables.containsKey(logicTable);
    }
    
    /**
     * Deduce actual table name from other actual table name in same binding table rule.
     *
     * @param dataSource data source name
     * @param logicTable logic table name
     * @param otherLogicTable other logic table name in same binding table rule
     * @param otherActualTable other actual table name in same binding table rule
     * @return actual table name
     * @throws ActualTableNotFoundException actual table not found exception
     * @throws BindingTableNotFoundException binding table not found exception
     */
    public String getBindingActualTable(final String dataSource, final String logicTable, final String otherLogicTable, final String otherActualTable) {
        Optional<ShardingTable> otherShardingTable = Optional.ofNullable(shardingTables.get(otherLogicTable));
        int index = otherShardingTable.map(optional -> optional.findActualTableIndex(dataSource, otherActualTable)).orElse(-1);
        if (-1 == index) {
            throw new ActualTableNotFoundException(dataSource, otherActualTable);
        }
        Optional<ShardingTable> shardingTable = Optional.ofNullable(shardingTables.get(logicTable));
        if (shardingTable.isPresent()) {
            return shardingTable.get().getActualDataNodes().get(index).getTableName();
        }
        throw new BindingTableNotFoundException(dataSource, logicTable, otherActualTable);
    }
    
    /**
     * Get list of logical table.
     *
     * @return logical tables.
     */
    public Collection<String> getAllLogicTables() {
        return shardingTables.keySet();
    }
    
    /**

View on GitHub (pinned to e952770a21)

Solutions

1. Give every table in the binding group identical topology: same data sources and same actual table count per data source.
2. Verify the binding group members with SHOW SHARDING BINDING TABLE RULES and remove/fix entries whose actualDataNodes differ.
3. Refresh metadata (or restart) after rule changes so binding rules are rebuilt from consistent configuration.

Example fix

-- before: members of one binding group differ
CREATE SHARDING BINDING TABLE RULES (t_order, t_order_item);
t_order:      ds_${0..1}.t_order_${0..3}
t_order_item: ds_0.t_order_item_0

-- after: aligned
CREATE SHARDING BINDING TABLE RULES (t_order, t_order_item);
t_order:      ds_${0..1}.t_order_${0..3}
t_order_item: ds_${0..1}.t_order_item_${0..3}

// Validate binding-group topology symmetry before enabling a binding rule
boolean symmetric(ShardingTable a, ShardingTable b) {
    Map<String, Long> ma = a.getActualDataNodes().stream().collect(groupingBy(DataNode::getDataSourceName, counting()));
    Map<String, Long> mb = b.getActualDataNodes().stream().collect(groupingBy(DataNode::getDataSourceName, counting()));
    return ma.equals(mb);
}

try {
    rs = stmt.executeQuery(joinSql);
} catch (final ActualTableNotFoundException ex) {
    // message shows ds + actual table; repair that table's actualDataNodes and retry
}

When it happens

Trigger: Binding-table routing resolves the actual table for a second table in the group from a first table's (dataSource, actualTable); the first table's actual table is not present in its own rule for that data source — mismatched actualDataNodes between tables in one binding group, or an unknown otherLogicTable.

Common situations: Binding tables (BOUND TABLE TABLES t_order, t_order_item) configured with different table counts or different data source sets; adding a table to a binding group before aligning its topology; stale metadata after DistSQL rule changes.

Related errors

• 40
• 41
• 57
• 1
• 5

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