{"record":{"id":"ccafec30fc9f53d7","repo":"MyCATApache/Mycat-Server","slug":"can-t-find-hint-schema-hintsqlvalue","errorCode":null,"errorMessage":"can't find hint schema:{hintSQLValue}","messagePattern":"can't find hint schema:(.+?)","errorType":"exception","errorClass":"SQLNonTransientException","httpStatus":null,"severity":"error","filePath":"src/main/java/io/mycat/route/handler/HintSchemaHandler.java","lineNumber":55,"sourceCode":"\t * @param charset\n\t * @param info\n\t * @param cachePool\n\t * @param hintSQLValue\n\t * @return\n\t * @throws SQLNonTransientException\n\t */\n\t@Override\n\tpublic RouteResultset route(SystemConfig sysConfig, SchemaConfig schema,\n\t\t\tint sqlType, String realSQL, String charset, ServerConnection sc,\n\t\t\tLayerCachePool cachePool, String hintSQLValue,int hintSqlType, Map hintMap)\n\t\t\tthrows SQLNonTransientException {\n\t    SchemaConfig tempSchema = MycatServer.getInstance().getConfig().getSchemas().get(hintSQLValue);\n\t\tif (tempSchema != null) {\n\t\t\treturn routeStrategy.route(sysConfig, tempSchema, sqlType, realSQL, charset, sc, cachePool);\n\t\t} else {\n\t\t\tString msg = \"can't find hint schema:\" + hintSQLValue;\n\t\t\tLOGGER.warn(msg);\n\t\t\tthrow new SQLNonTransientException(msg);\n\t\t}\n\t}\n}\n","sourceCodeStart":37,"sourceCodeEnd":59,"githubUrl":"https://github.com/MyCATApache/Mycat-Server/blob/65f8d8beb752f935752f2a0eec0ab017facab9ef/src/main/java/io/mycat/route/handler/HintSchemaHandler.java#L37-L59","documentation":"HintSchemaHandler.route() handles the /*+ schema=name */ hint by looking up hintSQLValue in MycatServer's configured schemas and routing through the found SchemaConfig. When no schema with that name is configured, it throws SQLNonTransientException after logging a warning. The statement cannot be routed because the hinted schema is unknown.","triggerScenarios":"Sending SQL with a hint like /*!mycat: schema = schema1*/ where schema1 is not present in the <schema> definitions loaded from schema.xml, including typos, schemas removed after a reload, or hints written against another environment's config.","commonSituations":"Hint references a logical schema that was renamed; application config copied from another environment with different schema names; case sensitivity or extra whitespace in the hint value; schema.xml reload failed so the expected schema was never loaded.","solutions":["Use a schema name that exists in schema.xml exactly as declared; verify with show @@schema on the Mycat admin port.","Fix typos or whitespace/case mismatches in the hint comment.","If the schema was renamed or removed, update all emitting clients or restore the schema definition and reload the config.","Confirm schema.xml reloaded successfully (check wrapper.log) so the hinted schema is actually registered."],"exampleFix":"// before\nString sql = \"/*!mycat: schema = testdb_old*/ SELECT 1\"; // SQLNonTransientException\n// after\nString sql = \"/*!mycat: schema = TESTDB*/ SELECT 1\"; // TESTDB defined in schema.xml","handlingStrategy":"validation","validationCode":"Set<String> schemas = MycatServer.getInstance().getConfig().getSchemas().keySet();\nif (!schemas.contains(hintSchema)) throw new IllegalArgumentException(\"unknown schema in hint: \" + hintSchema);","typeGuard":null,"tryCatchPattern":"try { stmt.execute(hintedSql); } catch (SQLNonTransientException e) { if (e.getMessage().startsWith(\"can't find hint schema:\")) { /* correct the hinted schema name */ } throw e; }","preventionTips":["Keep hint schema names in app config synchronized with schema.xml changes.","Confirm the schema is loaded after every config reload via show @@schema.","Avoid hand-typing hint values; reference a constants file generated from the Mycat config."],"tags":["sql","hint","schema","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"}