apache/shardingsphere · error · BindingTableNotFoundException

5

5

Error message

Can not find binding actual table, data source is '%s', logic table is '%s', other actual table is '%s'.

What it means

BindingTableNotFoundException is thrown by BindingTableRule.getBindingActualTable when the other binding member resolved fine (a valid index was found in otherShardingTable) but the requested logicTable itself has no entry in this BindingTableRule's shardingTables map. That is, the table whose actual name should be derived is not part of the binding-table rule being consulted.

Source

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

     * @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();
    }
    
    /**
     * Get logic and actual tables.
     *
     * @param dataSource data source
     * @param logicTable logic table
     * @param actualTable actual table
     * @param availableLogicBindingTables available logic binding tables

View on GitHub (pinned to e952770a21)

Solutions

1. Re-apply the binding table rule so it contains every member table (DROP + CREATE SHARDING BINDING TABLE RULES with the full list).
2. Check that each bound table also has a sharding table rule (binding members must all be sharded tables).
3. Restart/refresh metadata if rules were altered while the Proxy was serving traffic to rebuild BindingTableRule consistently.

Example fix

-- before: binding rule references a table with no sharding rule
CREATE SHARDING BINDING TABLE RULES (t_order, t_bogus);

-- after: only fully configured sharded tables, all present
CREATE SHARDING BINDING TABLE RULES (t_order, t_order_item);

// Confirm every binding-group member is a configured sharded table
Collection<String> shardedTables = rule.getConfiguration().getTables().stream().map(ShardingTableRuleConfiguration::getLogicTable).collect(Collectors.toSet());
for (String group : rule.getConfiguration().getBindingTableGroups().stream().map(BindingTableRuleConfiguration::getReference).toList()) {
    for (String member : group.split(",")) {
        if (!shardedTables.contains(member)) { throw new IllegalStateException("Binding member missing rule: " + member); }
    }
}

try {
    rs = stmt.executeQuery(sql);
} catch (final BindingTableNotFoundException ex) {
    // re-apply binding rule with complete member list; refresh metadata; retry
}

When it happens

Trigger: getBindingActualTable(dataSource, logicTable, otherLogicTable, otherActualTable) is called where otherLogicTable exists in the rule (index != -1) but shardingTables.get(logicTable) is null — e.g. rule lookup inconsistency where the binding rule knows the driver table but not the table being joined.

Common situations: Corrupted/stale binding rule metadata after partial DistSQL updates; concurrent rule alteration while queries run; programmatically built BindingTableRule missing one member that configuration elsewhere implies.

Related errors

• 1
• 4
• 1
• 41
• 37

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