apache/shardingsphere · error · DataSourceHintNotExistsException

0

0

Error message

Hint data source '%s' does not exist.

What it means

SQLRouteEngine.findDataSourceByHint resolves a forced data source from HintManager (JDBC) or the SQL hint (proxy) and validates it against the database's configured storage units. If the resolved name is present but not a key in the storageUnits map, it throws DataSourceHintNotExistsException — the hint names something the logical database simply does not contain.

Source

Thrown at infra/route/core/src/main/java/org/apache/shardingsphere/infra/route/engine/SQLRouteEngine.java:124

    
    @SuppressWarnings({"unchecked", "rawtypes"})
    private RouteContext route(final QueryContext queryContext, final RuleMetaData globalRuleMetaData, final ShardingSphereDatabase database,
                               final Map<ShardingSphereRule, SQLRouter> routers, final Collection<String> tableNames, final RouteContext routeContext) {
        RouteContext result = routeContext;
        for (Entry<ShardingSphereRule, SQLRouter> entry : routers.entrySet()) {
            if (result.getRouteUnits().isEmpty() && entry.getValue() instanceof EntranceSQLRouter) {
                result = ((EntranceSQLRouter) entry.getValue()).createRouteContext(queryContext, globalRuleMetaData, database, entry.getKey(), tableNames, props);
            } else if (entry.getValue() instanceof DecorateSQLRouter) {
                ((DecorateSQLRouter) entry.getValue()).decorateRouteContext(result, queryContext, database, entry.getKey(), tableNames, props);
            }
        }
        return result;
    }
    
    private Optional<String> findDataSourceByHint(final HintValueContext hintValueContext, final Map<String, StorageUnit> storageUnits) {
        Optional<String> result = HintManager.isInstantiated() && HintManager.getDataSourceName().isPresent() ? HintManager.getDataSourceName() : hintValueContext.findHintDataSourceName();
        if (result.isPresent() && !storageUnits.containsKey(result.get())) {
            throw new DataSourceHintNotExistsException(result.get());
        }
        return result;
    }
}

View on GitHub (pinned to e952770a21)

Solutions

1. Use the exact storage unit name as configured under mode/database storage_units (or the legacy datasource name) in the ShardingSphere YAML — verify case and separators.
2. Read the configured names at startup (e.g. from ShardingSphereDatabase storage units) and validate the constant against them, failing fast on mismatch.
3. Clear the hint when it is no longer needed: HintManager.clear() or omit the SQL hint, so routing falls back to normal rules.

Example fix

// before
HintManager.getInstance().setDataSourceName("write_ds"); // not a configured storage unit

// after
HintManager.getInstance().setDataSourceName("write-ds"); // matches storage_units name in YAML

Set<String> units = database.getStorageUnits().keySet();
if (!units.contains(hintDataSourceName)) { throw new IllegalArgumentException("unknown storage unit: " + hintDataSourceName + ", have: " + units); }

try { HintManager.getInstance().setDataSourceName(name); ... } finally { HintManager.clear(); } // prevent stale hints leaking to next statements

When it happens

Trigger: HintManager.setDataSourceName('write_ds') when the configured storage units are named 'write-ds'/'read-ds'; SQL hint /* SHARDINGSPHERE_HINT: SHARDINGSPHERE_DATASOURCE_NAME = x */ where x is a typo or belongs to a different logical database; renaming storage units in YAML without updating clients that hard-code hint names.

Common situations: Environment drift between config files (dev uses ds_0, prod uses write_ds); copy-pasting hint code from another project; after migrating mode/cluster configuration the storage unit names changed but application constants did not.

Related errors

• 41
• 1
• 4
• 40
• 33

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