MyCATApache/Mycat-Server · error · SQLNonTransientException

bad insert sql (sharding column: not provided,

Error message

bad insert sql (sharding column: not provided,

What it means

In parserSingleInsert, Mycat scans the INSERT column list for the table's partitionColumn. If the sharding column is not among the columns (isFound stays false), the target data node cannot be computed, so a SQLNonTransientException 'bad insert sql (sharding column:X not provided' is thrown with the statement appended.

Solutions

1. Add the sharding column and its value to the INSERT column list and VALUES.
2. Check that partitionColumn in schema.xml matches the actual column name (compared uppercase, backquotes removed).
3. If the column truly has no value, make it nullable-with-default and choose a different sharding column, or change the rule.

Example fix

// before (partitionColumn = customer_id)
INSERT INTO orders (id, name) VALUES (1, 'x');
// after
INSERT INTO orders (id, name, customer_id) VALUES (1, 'x', 100);

// Ensure the sharding column is in the column list before issuing the insert
function validateShardingColumn(columns, partitionColumn) {
  if (!columns.map(c => c.replace(/[`\"]/g, '').toUpperCase()).includes(partitionColumn.toUpperCase())) {
    throw new Error("INSERT must include sharding column: " + partitionColumn);
  }
}

When it happens

Trigger: Single-row INSERT into a sharded table whose explicit column list omits the configured partitionColumn, e.g. INSERT INTO orders (id, name) VALUES (...) where partitionColumn is customer_id.

Common situations: Column lists that predate a partitionColumn being added to config; ORM partial inserts; case mismatch between the SQL column name and the uppercase partitionColumn in schema.xml.

Understand the failure class

Background: "missing required argument" and "the following required arguments were not provided": what required-argument errors mean and how to fix them — this error's family across 20 libraries.

Related errors

• joinKey not provided
• number of columns error
• number of values and columns have to match
• partition table, insert must provide ColumnList
• joinKey not provided :

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

Appendix: source

Thrown at src/main/java/io/mycat/route/parser/druid/impl/DruidInsertParser.java:203

			if(partitionColumn.equalsIgnoreCase(StringUtil.removeBackquote(insertStmt.getColumns().get(i).toString()))) {//找到分片字段
				isFound = true;
				String column = StringUtil.removeBackquote(insertStmt.getColumns().get(i).toString());

				String shardingValue = StringUtil.removeBackquote(getShardingValue(insertStmt.getValues().getValues().get(i)));
				insertStmt.getValues().getValues().set(i,new SQLCharExpr(shardingValue));
				ctx.setSql(insertStmt.toString());

				RouteCalculateUnit routeCalculateUnit = new RouteCalculateUnit();
				routeCalculateUnit.addShardingExpr(tableName, column, shardingValue);
				ctx.addRouteCalculateUnit(routeCalculateUnit);
				//mycat是单分片键，找到了就返回
				break;
			}
		}
		if(!isFound) {//分片表的
			String msg = "bad insert sql (sharding column:"+ partitionColumn + " not provided," + insertStmt;
			LOGGER.warn(msg);
			throw new SQLNonTransientException(msg);
		}
		// insert into .... on duplicateKey 
		//such as :INSERT INTO TABLEName (a,b,c) VALUES (1,2,3) ON DUPLICATE KEY UPDATE b=VALUES(b); 
		//INSERT INTO TABLEName (a,b,c) VALUES (1,2,3) ON DUPLICATE KEY UPDATE c=c+1;
		if(insertStmt.getDuplicateKeyUpdate() != null) {
			List<SQLExpr> updateList = insertStmt.getDuplicateKeyUpdate();
			for(SQLExpr expr : updateList) {
				SQLBinaryOpExpr opExpr = (SQLBinaryOpExpr)expr;
				String column = StringUtil.removeBackquote(opExpr.getLeft().toString().toUpperCase());
				if(column.equals(partitionColumn)) {
					String msg = "Sharding column can't be updated: " + tableName + " -> " + partitionColumn;
					LOGGER.warn(msg);
					throw new SQLNonTransientException(msg);
				}
			}
		}
	}
	

View on GitHub (pinned to 65f8d8beb7)