apache/shardingsphere · error · SQLFederationUnsupportedSQLException

SQL federation does not support SQL '%s'.

Error message

SQL federation does not support SQL '%s'.

What it means

SQLFederationEngine.execute0 wraps the whole federation pipeline (schema conversion, plan compilation, execution). Any exception not in NEED_THROW_EXCEPTION_TYPES is rethrown as SQLFederationUnsupportedSQLException with the SQL and a truncated reason, after resources are closed. It is the umbrella 'federation could not run this SQL' error — the real cause is in the proxied log line and the reason string.

Source

Thrown at kernel/sql-federation/core/src/main/java/org/apache/shardingsphere/sqlfederation/engine/SQLFederationEngine.java:231

            SQLFederationRelConverter converter = new SQLFederationRelConverter(compilerContext, getSchemaPath(sqlStatementContext),
                    sqlStatementContext.getSqlStatement().getDatabaseType(), processor.getConvention());
            schemaPlus = converter.getSchemaPlus();
            processor.prepare(prepareEngine, queryCallback, currentDatabaseName, currentSchemaName, federationContext, compilerContext, schemaPlus);
            SQLFederationExecutionPlan executionPlan = compileQuery(converter, currentDatabaseName,
                    currentSchemaName, federationContext, sqlStatementContext, queryContext.getSql(), processor.getConvention());
            logExecutionPlan(executionPlan, federationContext.getMetaData().getProps());
            resultSet = processor.executePlan(prepareEngine, queryCallback, executionPlan, converter, federationContext, schemaPlus);
            return resultSet;
            // CHECKSTYLE:OFF
        } catch (final Exception ex) {
            // CHECKSTYLE:ON
            String errorMessage = splitErrorMessage(ex);
            log.error("SQL Federation execute failed, sql {}, parameters {}, reason {}", queryContext.getSql(), queryContext.getParameters(), errorMessage);
            closeResources(federationContext);
            if (NEED_THROW_EXCEPTION_TYPES.stream().anyMatch(each -> each.isAssignableFrom(ex.getClass()))) {
                throw ex;
            }
            throw new SQLFederationUnsupportedSQLException(queryContext.getSql(), errorMessage);
        }
    }
    
    private String splitErrorMessage(final Exception ex) {
        return null == ex.getMessage() ? "" : ex.getMessage().substring(0, Math.min(ex.getMessage().length(), MAX_ERROR_MESSAGE_LENGTH));
    }
    
    private void closeResources(final SQLFederationContext federationContext) {
        try {
            processEngine.completeSQLExecution(federationContext.getProcessId());
            close();
            // CHECKSTYLE:OFF
        } catch (final Exception ex) {
            // CHECKSTYLE:ON
            log.warn("Failed to close SQL federation engine resources: {}", ex.getMessage());
        }
    }
    

View on GitHub (pinned to e952770a21)

Solutions

1. Read the 'reason' fragment in the exception message and cross-check with the proxy log line 'SQL Federation execute failed, sql ..., reason ...' for the full cause.
2. Rewrite the unsupported construct (see the underlying converter error) or add missing metadata.
3. Disable federation for this statement or rule (execution strategy NONE) to fall back to normal routed execution.
4. Upgrade ShardingSphere for broader federation coverage.

try {
    rs = federationExecutor.execute(...);
} catch (final SQLFederationUnsupportedSQLException ex) {
    log.warn("Federation unsupported, falling back: {}", ex.getMessage());
    rs = executeWithFederationDisabled(sql, params);
}

When it happens

Trigger: Executing a query with sql-federation enabled where any stage fails: unsupported expression/table conversion (errors 411-415), Calcite compilation errors, missing schema/column mapping, or execution-time failures not whitelisted for pass-through.

Common situations: Cross-shard queries with constructs the federation compiler does not support; views or joins that force federation; metadata/schema mismatches; version-dependent converter gaps.

Related errors

• unsupported CommonExpressionSegment
• unsupported TableSegment type: %s
• Unsupported interval unit
• Unsupported segment type: %s
• unsupported TextOrderByItemSegment

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