MyCATApache/Mycat-Server · error · IllegalArgumentException

columnValue: Please check if the format satisfied.

Error message

columnValue:{columnValue} Please check if the format satisfied.

What it means

PartitionByFileMap.calculate() looks up the column value in app2Partition (loaded from mapFile). Although the map keys are Objects, this catch triggers when numeric parsing of the column value throws NumberFormatException, meaning the value cannot be interpreted/matched to a configured partition entry. The library then throws this IllegalArgumentException.

Solutions

  1. Ensure the column value is a valid number matching keys in the map file, or add the actual value to the map file.
  2. Configure a defaultNode so unmapped values route somewhere instead of failing parse paths.
  3. Strip quotes/non-numeric characters from the value at the application or ETL layer before insert.

Example fix

// before
INSERT INTO t(id, type) VALUES(1, '"3"'); // quoted value
// after
INSERT INTO t(id, type) VALUES(1, '3');
Defensive patterns

Strategy: validation

Validate before calling

boolean ok = columnValue != null && columnValue.trim().matches("-?\\d+");

Try / catch

try {
    Integer node = partitionByFileMap.calculate(columnValue);
} catch (IllegalArgumentException e) {
    // fall back to defaultNode or reject with clear error
}

Prevention

When it happens

Trigger: Routing a row whose partition (map) column value is a non-numeric string that fails Number parsing in calculate(); value not present and DEFAULT_NODE resolution path still requires parsing; passing values like '12a' or quoted numbers.

Common situations: Map file in rule config lists integer keys but the application sends string keys; values contain quotes or whitespace; type of the sharding column in the table doesn't match the keys configured in the map file.

Understand the failure class

Background: "Invalid ... format", "must be in format X", "does not look like a ..." — invalid argument format errors across CLI tools and libraries — this error's family across 17 libraries.

Related errors

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

Appendix: source

Thrown at src/main/java/io/mycat/route/function/PartitionByFileMap.java:98

	}

	@Override
	public Integer calculate(String columnValue)  {
		try {
			Object value = columnValue;
			if (type == 0) {
				value = Integer.valueOf(columnValue);
			}
			Integer rst = null;
			Integer pid = app2Partition.get(value);
			if (pid != null) {
				rst = pid;
			} else {
				rst = app2Partition.get(DEFAULT_NODE);
			}
			return rst;
		} catch (NumberFormatException e){
			throw new IllegalArgumentException(new StringBuilder().append("columnValue:").append(columnValue).append(" Please check if the format satisfied.").toString(),e);
		}
	}
	
	@Override
	public int getPartitionNum() {
		Set<Integer> set = new HashSet<Integer>(app2Partition.values());
		int count = set.size();
		return count;
	}

	private void initialize() {
		BufferedReader in = null;
		try {
			// FileInputStream fin = new FileInputStream(new File(fileMapPath));
			InputStream fin = this.getClass().getClassLoader()
					.getResourceAsStream(mapFile);
			if (fin == null) {
				throw new RuntimeException("can't find class resource file "

View on GitHub (pinned to 65f8d8beb7)