MyCATApache/Mycat-Server · error · SQLNonTransientException

SQLNonTransientException(e) from catlet error handling

Error message

SQLNonTransientException(e) from catlet error handling

What it means

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.

Solutions

1. Check the wrapped cause in the SQLNonTransientException / the 'catlet error' log line to see the real failure.
2. Verify the hint syntax and fully-qualified catlet class name, and that the class is present on MyCat's classpath.
3. Fix the bug in the Catlet implementation (route/processSQL) that is throwing on this SQL.
4. If the catlet is unnecessary, remove the hint comment from the SQL so the default router handles it.

Example fix

// before
/*//!mycat:catlet=io.mycat.Cat letOld*/SELECT ...
// after
/*//!mycat:catlet=io.mycat.cache.DefaultCatlet*/SELECT ...

// before using a catlet hint, verify the class loads
String cls = "io.mycat.cache.DefaultCatlet";
Class.forName(cls); // throws ClassNotFoundException if missing
if (!Catlet.class.isAssignableFrom(Class.forName(cls))) throw new IllegalStateException(cls + " does not implement Catlet");

try {
  stmt.execute(hintedSql);
} catch (SQLNonTransientException e) {
  logger.error("catlet execution failed; cause={} sql={}", e.getCause(), hintedSql);
  // fall back to the SQL without the catlet hint
}

When it happens

Trigger: 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).

Common situations: 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.

Related errors

• can't find hint datanode
• can't find hint schema
• "can't find hint datanode:" + hintSQLValue
• "can't find hint schema:" + hintSQLValue
• schema: ,table: ,sql: is not allowed,because table is…

AI-assisted analysis of MyCATApache/Mycat-Server@65f8d8beb7 (2026-09-11). Data as JSON: /api/errors/801ec1e0a2156855. Report an issue: GitHub.

Appendix: source

Thrown at src/main/java/io/mycat/route/handler/HintCatletHandler.java:58

	@Override
	public RouteResultset route(SystemConfig sysConfig, SchemaConfig schema,
			int sqlType, String realSQL, String charset, ServerConnection sc,
			LayerCachePool cachePool, String hintSQLValue,int hintSqlType, Map hintMap)
			throws SQLNonTransientException {
		// sc.setEngineCtx ctx
		String cateletClass = hintSQLValue;
		if (LOGGER.isDebugEnabled()) {
			LOGGER.debug("load catelet class:" + hintSQLValue + " to run sql "
					+ realSQL);
		}
		try {
			Catlet catlet = (Catlet) MycatServer.getInstance()
					.getCatletClassLoader().getInstanceofClass(cateletClass);
			catlet.route(sysConfig, schema, sqlType, realSQL,charset, sc, cachePool);
			catlet.processSQL(realSQL, new EngineCtx(sc.getSession2()));
		} catch (Exception e) {
			LOGGER.warn("catlet error "+e);
			throw new SQLNonTransientException(e);
		}
		return null;
	}
}

View on GitHub (pinned to 65f8d8beb7)