MyCATApache/Mycat-Server · error · SQLNonTransientException

can't find table define in schema

Error message

can't find table define in schema {tableName} alias：{alias}, schema:{schemaName}

What it means

During SELECT routing, the table (or its alias) could not be matched to a tableConfig, and when the schema has no default dataNode there is nowhere to send the query, so SQLNonTransientException('can't find table define in schema ...') is thrown. It reports the table name, alias, and schema to help locate the config gap.

Solutions

Declare the missing table in schema.xml (<table name="..." .../>) and reload config
Add dataNode="..." to the <schema> element as a default node for undeclared tables
Qualify the table with the correct schema name or fix aliases so the router can match tableConfig

Example fix

// before (schema.xml)
<schema name="db" sqlMaxLimit="100"/>
// after
<schema name="db" sqlMaxLimit="100" dataNode="dn1"/>
  <table name="t_config" dataNode="dn1" type="global"/>

Defensive patterns

Strategy: validation

Validate before calling

// before querying
TableConfig tc = schema.getTables().get(tableName);
if (tc == null && (schema.getDataNode() == null || schema.getDataNode().isEmpty())) {
  throw new IllegalStateException("table " + tableName + " not defined in schema " + schema.getName());
}

Try / catch

try { routeSelect(sql); } catch (SQLNonTransientException e) { if (e.getMessage().startsWith("can't find table define in schema")) { /* declare table or set default dataNode */ } throw e; }

Prevention

Declare every queryable table in schema.xml
Set a schema-level default dataNode as safety net
Standardize table/alias naming to ease router matching

When it happens

Trigger: SELECT statements referencing a table or alias that is not defined in the schema's tables map, where the <schema> element has no dataNode attribute; frequently hit for aliased or non-qualified names the router cannot resolve.

Common situations: Querying tables not declared in schema.xml; using aliases/subqueries that confuse table-name resolution; information_schema or system tables not configured; connecting to a schema whose tables are all sharded but the SQL references an undeclared helper table.

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/9900f97c6e629a72. Report an issue: GitHub.

Appendix: source

Thrown at src/main/java/io/mycat/route/util/RouterUtil.java:1264

		for(String tableName : tables) {

			TableConfig tableConfig = schema.getTables().get(tableName.toUpperCase());

			if(tableConfig == null) {
				//add 如果表读取不到则先将表名从别名中读取转化后再读取
				String alias = ctx.getTableAliasMap().get(tableName);
				if(!StringUtil.isEmpty(alias)){
					tableConfig = schema.getTables().get(alias.toUpperCase());
				}

				if(tableConfig == null){
					if (StringUtils.isNotEmpty(schema.getDataNode())) {
						return routeToSingleNode(rrs, schema.getDataNode(), ctx.getSql());
					} else {
						String msg = "can't find table define in schema " + tableName + " alias：" + alias + ", schema:"
								+ schema.getName();
						LOGGER.warn(msg);
						throw new SQLNonTransientException(msg);
					}
				}

			}
			if(tableConfig.isGlobalTable()) {//全局表
				if(tablesRouteMap.get(tableName) == null) {
					tablesRouteMap.put(tableName, new HashSet<String>());
				}
				tablesRouteMap.get(tableName).addAll(tableConfig.getDataNodes());
			} else if(tablesRouteMap.get(tableName) == null) { //余下的表都是单库表
				tablesRouteMap.put(tableName, new HashSet<String>());
				tablesRouteMap.get(tableName).addAll(tableConfig.getDataNodes());
			}

			if(tableConfig.getDistTables().size() > 0) {
				Map<String, List<String>> subTablesmap = rrs.getSubTableMaps();
				if (subTablesmap == null) {
					subTablesmap = Maps.newHashMap();

View on GitHub (pinned to 65f8d8beb7)