apache/shardingsphere · error · NoShardingTableRouteFactorException

57

57

Error message

Can not find routing table factor, data source '%s', actual table '%s'.

What it means

NoShardingTableRouteFactorException is thrown by ShardingCartesianRouteEngine when building the cartesian product of route contexts for a complex (multi-table) statement: for a given data source and actual table, no participating route context contains a matching table mapper (findTableMapper returns empty in every context). The engine cannot assemble a consistent routing table group, so it reports the missing routing factor with the data source and actual table names.

Source

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

        List<Set<RouteMapper>> result = new ArrayList<>(actualTableGroups.size());
        for (Set<String> each : actualTableGroups) {
            Set<RouteMapper> routingTableGroup = new LinkedHashSet<>(each.size(), 1F);
            for (String actualTable : each) {
                routingTableGroup.add(findRoutingTable(dataSource, actualTable));
            }
            result.add(routingTableGroup);
        }
        return result;
    }
    
    private RouteMapper findRoutingTable(final String dataSource, final String actualTable) {
        for (RouteContext each : routeContexts) {
            Optional<RouteMapper> result = each.findTableMapper(dataSource, actualTable);
            if (result.isPresent()) {
                return result.get();
            }
        }
        throw new NoShardingTableRouteFactorException(dataSource, actualTable);
    }
    
    private Collection<RouteUnit> getRouteUnits(final String dataSource, final Set<List<RouteMapper>> cartesianRoutingTableGroups) {
        Collection<RouteUnit> result = new LinkedHashSet<>(cartesianRoutingTableGroups.size(), 1F);
        RouteMapper dataSourceMapper = new RouteMapper(dataSource, dataSource);
        for (List<RouteMapper> each : cartesianRoutingTableGroups) {
            result.add(new RouteUnit(dataSourceMapper, new LinkedList<>(each)));
        }
        return result;
    }
}

View on GitHub (pinned to e952770a21)

Solutions

1. Align the actualDataNodes topology (same data sources, same per-data-source table counts) for every sharded table appearing in the statement.
2. Add an equality join condition on the binding/sharding keys so the statement uses binding-table routing instead of the cartesian engine.
3. Verify recently changed table rules were applied to all data sources (no stale rule metadata) — refresh the metadata or restart Proxy.

Example fix

# before: t_order covers ds_0/ds_1, t_order_item only ds_0
actualDataNodes: ds_${0..1}.t_order_${0..3}
actualDataNodes: ds_0.t_order_item_${0..3}

# after: aligned topologies
actualDataNodes: ds_${0..1}.t_order_${0..3}
actualDataNodes: ds_${0..1}.t_order_item_${0..3}

// Before running multi-table SQL, assert aligned topologies
List<Integer> countsPerDs(ShardingTable t) { /* group actualDataNodes by ds, count */ return List.of(); }
if (!countsPerDs(orderTable).equals(countsPerDs(itemTable))) {
    throw new IllegalStateException("Topologies differ; complex routing will fail");
}

try {
    rs = stmt.executeQuery(joinSql);
} catch (final NoShardingTableRouteFactorException ex) {
    // log ds + actual table from message; fix rule topology, then retry once after metadata refresh
}

When it happens

Trigger: Complex routing (SQL touching multiple sharded tables without a single common sharding key) where the per-table standard route contexts disagree: an actual table routed in one context has no counterpart mapper in the others for that data source — typically caused by inconsistent actualDataNodes/topology among tables in the statement.

Common situations: Joining sharded tables whose actual data node counts differ per data source; partially updated rules where one table was added to ds_1 but the other was not; binding-table groups containing tables with mismatched topologies.

Related errors

• 40
• 1
• 4
• 41
• 33

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