{"record":{"id":"801ec1e0a2156855","repo":"MyCATApache/Mycat-Server","slug":"sqlnontransientexception-e-from-catlet-error-hand","errorCode":null,"errorMessage":"SQLNonTransientException(e) from catlet error handling","messagePattern":"SQLNonTransientException\\(e\\) from catlet error handling","errorType":"exception","errorClass":"SQLNonTransientException","httpStatus":null,"severity":"error","filePath":"src/main/java/io/mycat/route/handler/HintCatletHandler.java","lineNumber":58,"sourceCode":"\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\t// sc.setEngineCtx ctx\n\t\tString cateletClass = hintSQLValue;\n\t\tif (LOGGER.isDebugEnabled()) {\n\t\t\tLOGGER.debug(\"load catelet class:\" + hintSQLValue + \" to run sql \"\n\t\t\t\t\t+ realSQL);\n\t\t}\n\t\ttry {\n\t\t\tCatlet catlet = (Catlet) MycatServer.getInstance()\n\t\t\t\t\t.getCatletClassLoader().getInstanceofClass(cateletClass);\n\t\t\tcatlet.route(sysConfig, schema, sqlType, realSQL,charset, sc, cachePool);\n\t\t\tcatlet.processSQL(realSQL, new EngineCtx(sc.getSession2()));\n\t\t} catch (Exception e) {\n\t\t\tLOGGER.warn(\"catlet error \"+e);\n\t\t\tthrow new SQLNonTransientException(e);\n\t\t}\n\t\treturn null;\n\t}\n}\n","sourceCodeStart":40,"sourceCodeEnd":63,"githubUrl":"https://github.com/MyCATApache/Mycat-Server/blob/65f8d8beb752f935752f2a0eec0ab017facab9ef/src/main/java/io/mycat/route/handler/HintCatletHandler.java#L40-L63","documentation":"HintCatletHandler.route instantiates the configured Catlet class via MyCatServer's CatletClassLoader and runs its route()/processSQL(). Any exception thrown inside the catlet (or during class instantiation) is logged and rethrown wrapped in SQLNonTransientException, which surfaces to the client as a fatal, non-retryable SQL error.","triggerScenarios":"Sending a SQL statement with a catlet hint (e.g. /*!mycat:catlet=...*/) where the catlet class name is wrong, the class cannot be loaded, or the catlet's route/processSQL throws (bad SQL parsing inside the catlet, NPEs from misconfigured schema).","commonSituations":"Typo in the catlet class name in the hint comment, catlet class not on the classpath / not compiled against current MyCat API, catlet logic failing on the specific SQL, or cachePool/schema config mismatch.","solutions":["Check the wrapped cause in the SQLNonTransientException / the 'catlet error' log line to see the real failure.","Verify the hint syntax and fully-qualified catlet class name, and that the class is present on MyCat's classpath.","Fix the bug in the Catlet implementation (route/processSQL) that is throwing on this SQL.","If the catlet is unnecessary, remove the hint comment from the SQL so the default router handles it."],"exampleFix":"// before\n/*//!mycat:catlet=io.mycat.Cat letOld*/SELECT ...\n// after\n/*//!mycat:catlet=io.mycat.cache.DefaultCatlet*/SELECT ...","handlingStrategy":"try-catch","validationCode":"// before using a catlet hint, verify the class loads\nString cls = \"io.mycat.cache.DefaultCatlet\";\nClass.forName(cls); // throws ClassNotFoundException if missing\nif (!Catlet.class.isAssignableFrom(Class.forName(cls))) throw new IllegalStateException(cls + \" does not implement Catlet\");","typeGuard":null,"tryCatchPattern":"try {\n  stmt.execute(hintedSql);\n} catch (SQLNonTransientException e) {\n  logger.error(\"catlet execution failed; cause={} sql={}\", e.getCause(), hintedSql);\n  // fall back to the SQL without the catlet hint\n}","preventionTips":["Verify the catlet class name and classpath before deploying hints.","Unit-test catlets against the SQL shapes they will receive.","Rebuild catlets against the MyCat API version in production."],"tags":["routing","catlet","hint","sql-non-transient"],"backgroundTag":"class-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"}