{"record":{"id":"77a67f4ae5c2b545","repo":"apache/shardingsphere","slug":"0-77a67f","errorCode":"0","errorMessage":"Hint data source '%s' does not exist.","messagePattern":"Hint data source '(.+?)' does not exist\\.","errorType":"exception","errorClass":"DataSourceHintNotExistsException","httpStatus":null,"severity":"error","filePath":"infra/route/core/src/main/java/org/apache/shardingsphere/infra/route/engine/SQLRouteEngine.java","lineNumber":124,"sourceCode":"    \n    @SuppressWarnings({\"unchecked\", \"rawtypes\"})\n    private RouteContext route(final QueryContext queryContext, final RuleMetaData globalRuleMetaData, final ShardingSphereDatabase database,\n                               final Map<ShardingSphereRule, SQLRouter> routers, final Collection<String> tableNames, final RouteContext routeContext) {\n        RouteContext result = routeContext;\n        for (Entry<ShardingSphereRule, SQLRouter> entry : routers.entrySet()) {\n            if (result.getRouteUnits().isEmpty() && entry.getValue() instanceof EntranceSQLRouter) {\n                result = ((EntranceSQLRouter) entry.getValue()).createRouteContext(queryContext, globalRuleMetaData, database, entry.getKey(), tableNames, props);\n            } else if (entry.getValue() instanceof DecorateSQLRouter) {\n                ((DecorateSQLRouter) entry.getValue()).decorateRouteContext(result, queryContext, database, entry.getKey(), tableNames, props);\n            }\n        }\n        return result;\n    }\n    \n    private Optional<String> findDataSourceByHint(final HintValueContext hintValueContext, final Map<String, StorageUnit> storageUnits) {\n        Optional<String> result = HintManager.isInstantiated() && HintManager.getDataSourceName().isPresent() ? HintManager.getDataSourceName() : hintValueContext.findHintDataSourceName();\n        if (result.isPresent() && !storageUnits.containsKey(result.get())) {\n            throw new DataSourceHintNotExistsException(result.get());\n        }\n        return result;\n    }\n}\n","sourceCodeStart":106,"sourceCodeEnd":129,"githubUrl":"https://github.com/apache/shardingsphere/blob/e952770a215630a3659c75d64369168cd3e26b82/infra/route/core/src/main/java/org/apache/shardingsphere/infra/route/engine/SQLRouteEngine.java#L106-L129","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["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.","Read the configured names at startup (e.g. from ShardingSphereDatabase storage units) and validate the constant against them, failing fast on mismatch.","Clear the hint when it is no longer needed: HintManager.clear() or omit the SQL hint, so routing falls back to normal rules."],"exampleFix":"// before\nHintManager.getInstance().setDataSourceName(\"write_ds\"); // not a configured storage unit\n\n// after\nHintManager.getInstance().setDataSourceName(\"write-ds\"); // matches storage_units name in YAML","handlingStrategy":"validation","validationCode":"Set<String> units = database.getStorageUnits().keySet();\nif (!units.contains(hintDataSourceName)) { throw new IllegalArgumentException(\"unknown storage unit: \" + hintDataSourceName + \", have: \" + units); }","typeGuard":null,"tryCatchPattern":"try { HintManager.getInstance().setDataSourceName(name); ... } finally { HintManager.clear(); } // prevent stale hints leaking to next statements","preventionTips":["Derive hint datasource names from configuration, not hard-coded constants.","Always HintManager.close()/clear() after use so stale names do not leak.","Validate hint names at application startup against the loaded storage units."],"tags":["routing","hint","datasource","configuration"],"backgroundTag":null,"analyzedSha":"e952770a215630a3659c75d64369168cd3e26b82","analyzedAt":"2026-08-14T13:54:53.392Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}