What causes "can't find hint schema:{hintSQLValue}" in MyCATApache/Mycat-Server?

Use a schema name that exists in schema.xml exactly as declared; verify with show @@schema on the Mycat admin port.

MyCATApache/Mycat-Server · error · SQLNonTransientException

can't find hint schema

Error message

can't find hint schema:{hintSQLValue}

What it means

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.

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.

Example fix

// before
String sql = "/*!mycat: schema = testdb_old*/ SELECT 1"; // SQLNonTransientException
// after
String sql = "/*!mycat: schema = TESTDB*/ SELECT 1"; // TESTDB defined in schema.xml

Defensive patterns

Strategy: validation

Validate before calling

Set<String> schemas = MycatServer.getInstance().getConfig().getSchemas().keySet();
if (!schemas.contains(hintSchema)) throw new IllegalArgumentException("unknown schema in hint: " + hintSchema);

Try / catch

try { stmt.execute(hintedSql); } catch (SQLNonTransientException e) { if (e.getMessage().startsWith("can't find hint schema:")) { /* correct the hinted schema name */ } throw e; }

Prevention

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.

When it happens

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

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

Understand the failure class

Background: "Not found" and "does not exist" errors: why "Task not found", "No such folder", and "Can't find" fire when a lookup comes back empty — this error's family across 14 libraries.

Related errors

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

Appendix: source

Thrown at src/main/java/io/mycat/route/handler/HintSchemaHandler.java:55

	 * @param charset
	 * @param info
	 * @param cachePool
	 * @param hintSQLValue
	 * @return
	 * @throws SQLNonTransientException
	 */
	@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 {
	    SchemaConfig tempSchema = MycatServer.getInstance().getConfig().getSchemas().get(hintSQLValue);
		if (tempSchema != null) {
			return routeStrategy.route(sysConfig, tempSchema, sqlType, realSQL, charset, sc, cachePool);
		} else {
			String msg = "can't find hint schema:" + hintSQLValue;
			LOGGER.warn(msg);
			throw new SQLNonTransientException(msg);
		}
	}
}

View on GitHub (pinned to 65f8d8beb7)