{"record":{"id":"ba0f4e3171c1490b","repo":"MyCATApache/Mycat-Server","slug":"can-t-find-hint-datanode-hintsqlvalue","errorCode":null,"errorMessage":"can't find hint datanode:{hintSQLValue}","messagePattern":"can't find hint datanode:(.+?)","errorType":"exception","errorClass":"SQLNonTransientException","httpStatus":null,"severity":"error","filePath":"src/main/java/io/mycat/route/handler/HintDataNodeHandler.java","lineNumber":51,"sourceCode":"\t@Override\n\tpublic RouteResultset route(SystemConfig sysConfig, SchemaConfig schema, int sqlType, String realSQL,\n\t\t\tString charset, ServerConnection sc, LayerCachePool cachePool, String hintSQLValue,int hintSqlType, Map hintMap)\n\t\t\t\t\tthrows SQLNonTransientException {\n\t\t\n\t\tString stmt = realSQL;\n\t\t\n\t\tif (LOGGER.isDebugEnabled()) {\n\t\t\tLOGGER.debug(\"route datanode sql hint from \" + stmt);\n\t\t}\n\t\t\n\t\tRouteResultset rrs = new RouteResultset(stmt, sqlType);\t\t\n\t\tPhysicalDBNode dataNode = MycatServer.getInstance().getConfig().getDataNodes().get(hintSQLValue);\n\t\tif (dataNode != null) {\t\t\t\n\t\t\trrs = RouterUtil.routeToSingleNode(rrs, dataNode.getName(), stmt);\n\t\t} else {\n\t\t\tString msg = \"can't find hint datanode:\" + hintSQLValue;\n\t\t\tLOGGER.warn(msg);\n\t\t\tthrow new SQLNonTransientException(msg);\n\t\t}\n\n\t\t// 处理导入参数初始化\n\t\tif(rrs.getSqlType() == ServerParse.LOAD_DATA_INFILE_SQL){\n\t\t\tLOGGER.info(\"load data use annotation datanode\");\n\t\t\trrs.getNodes()[0].setLoadData(parseLoadDataPram(stmt , charset));\n\t\t}\n\t\t\n\t\treturn rrs;\n\t}\n\n\t// 初始化导入参数\n\tprivate LoadData parseLoadDataPram(String sql , String connectionCharset)\n\t{\n\t\tSQLStatementParser parser = new MycatStatementParser(sql);\n\t\tMySqlLoadDataInFileStatement statement = (MySqlLoadDataInFileStatement) parser.parseStatement();\n\n\t\tLoadData loadData = new LoadData();","sourceCodeStart":33,"sourceCodeEnd":69,"githubUrl":"https://github.com/MyCATApache/Mycat-Server/blob/65f8d8beb752f935752f2a0eec0ab017facab9ef/src/main/java/io/mycat/route/handler/HintDataNodeHandler.java#L33-L69","documentation":"HintDataNodeHandler.route() handles the /*+ datanode=name */ Mycat hint by looking up hintSQLValue in MycatServer's configured datanodes. If no datanode with that name exists, it logs a warning and throws SQLNonTransientException. The SQL is not routed anywhere because the hinted target does not exist.","triggerScenarios":"Executing SQL with a hint like /*!mycat: datanode = dn1*/ (or the /*+ ... */ form) where dn1 is not defined in schema.xml's <dataNode> entries, including typos, stale names after a config change, or hints targeting datanodes on a different Mycat instance.","commonSituations":"Typo in the hint comment; renaming datanodes during scaling operations while application code still emits the old hint; environment mismatch where test configs name datanodes differently than production; whitespace/case issues in the hint value.","solutions":["Correct the hint to an existing datanode name exactly as declared in schema.xml (e.g. /*+ mycat:datanode=dn1 */).","Cross-check the datanode name in Mycat's running config (show @@datanode) and fix the application's hint string.","If the datanode was removed/renamed, either restore the old name in schema.xml or update all clients that send the hint.","Add client-side validation of hint names against known datanodes before sending SQL."],"exampleFix":"// before\nString sql = \"/*!mycat: datanode = dataNodeOld*/ SELECT * FROM t\"; // SQLNonTransientException\n// after\nString sql = \"/*!mycat: datanode = dn1*/ SELECT * FROM t\"; // dn1 exists in schema.xml","handlingStrategy":"validation","validationCode":"Set<String> known = MycatServer.getInstance().getConfig().getDataNodes().keySet();\nif (!known.contains(hintDataNode)) throw new IllegalArgumentException(\"unknown datanode in hint: \" + hintDataNode);","typeGuard":null,"tryCatchPattern":"try { stmt.execute(hintedSql); } catch (SQLNonTransientException e) { if (e.getMessage().startsWith(\"can't find hint datanode:\")) { /* fix hint name against schema.xml datanodes */ } throw e; }","preventionTips":["Generate hint names from the same source of truth as schema.xml, not hand-written strings.","Re-check hints after any datanode rename/removal migration.","Verify hints with show @@datanode on the Mycat management port before rollout."],"tags":["sql","hint","datanode","routing"],"backgroundTag":"entity-not-found","analyzedSha":"65f8d8beb752f935752f2a0eec0ab017facab9ef","analyzedAt":"2026-09-11T00:12:21.696Z","contentChangedAt":"2026-09-11T00:12:21.696Z","schemaVersion":2},"datasetVersion":"2026-09-16T04:17:20.429Z"}