MyCATApache/Mycat-Server · error · SQLNonTransientException

"can't find hint schema:" + hintSQLValue

Error message

"can't find hint schema:" + hintSQLValue

What it means

The /*schema=...*/ hint overrides which logical schema a statement is routed against. HintSchemaHandler looks up hintSQLValue in the config's schemas map; if no schema of that name is configured, routing cannot proceed and a SQLNonTransientException is thrown.

Solutions

1. Correct the hint value to match an existing <schema name="..."> in schema.xml
2. Verify the schema exists with show @@schema or the config dump, then retry
3. Remove the hint and rely on the connection's default schema (USE statement / connection URL)

Example fix

-- before
/*schema=shop_db*/ SELECT * FROM orders LIMIT 1;
-- after (schema.xml defines <schema name="shopdb">)
/*schema=shopdb*/ SELECT * FROM orders LIMIT 1;

if (!mycatConfig.getSchemas().containsKey(schemaHint)) {
    throw new IllegalArgumentException("unknown schema hint: " + schemaHint);
}

try { queryWithSchemaHint(name, sql); } catch (SQLNonTransientException e) { if (e.getMessage().startsWith("can't find hint schema")) { fallBackToDefaultSchema(sql); } else throw e; }

When it happens

Trigger: Sending `/* schema=shopdb */ SELECT ...` (or HintManager.useSchema("shopdb")) where 'shopdb' is not a <schema name="..."> in Mycat's schema.xml, or the schema was dropped/renamed on reload.

Common situations: Typo or wrong-case schema name in the hint; environment drift (hint hard-coded for a schema that exists only in another environment); config reloaded without the schema.

Understand the failure class

Background: 'Could not be found', 'does not exist', 'not found in database': the resource-not-found family when an ID, slug, key, or URI lookup comes back empty — this error's family across 20 libraries.

Related errors

• can't find hint schema
• "can't find hint datanode:" + hintSQLValue
• can't find hint datanode
• SQLNonTransientException(e) from catlet error handling
• ER_PARSE_ERROR

AI-assisted analysis of MyCATApache/Mycat-Server@65f8d8beb7 (2026-09-11). Data as JSON: /api/errors/934fcb40159dfa6a. 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)