Tencent/APIJSON · error · IllegalArgumentException

{}:value 中key不合法！不支持 ! 以外的逻辑符 ！

Error message

{}:value 中key不合法！不支持 ! 以外的逻辑符 ！

What it means

Thrown by gainEqualString when, after stripping the optional '!' (NOT) suffix and the optional '[' / '{' length-function suffix, the remaining column string fails StringUtil.isName(). This means the key contains characters not legal for a column identifier (e.g. '&', '|', or punctuation), so the library refuses to embed it in SQL.

Source

Thrown at APIJSONORM/src/main/java/apijson/orm/AbstractSQLConfig.java:4043

		default:  // TODO MySQL JSON类型的字段对比 key='[]' 会无结果！ key LIKE '[1, 2, 3]'  //TODO MySQL , 后面有空格！
			return gainEqualString(key, column, value, rawSQL);
		}
	}


	public String gainEqualString(String key, String column, Object value, String rawSQL) throws Exception {
		if (value != null && JSON.isBoolOrNumOrStr(value) == false && value instanceof Subquery == false) {
			throw new IllegalArgumentException(key + ":value 中value不合法！非PUT请求只支持 [Boolean, Number, String] 内的类型 ！");
		}

		boolean not = column.endsWith("!"); // & | 没有任何意义，写法多了不好控制
		if (not) {
			column = column.substring(0, column.length() - 1);
		}

		String rc = column.endsWith("[") || column.endsWith("{") ? column.substring(0, column.length() - 1) : column;
		if (StringUtil.isName(rc) == false) {
			throw new IllegalArgumentException(key + ":value 中key不合法！不支持 ! 以外的逻辑符 ！");
		}

		String logic = value == null && rawSQL == null ? (not ? SQL.IS_NOT : SQL.IS) : (not ? " != " : " = ");
		return gainKey(column) + logic + (value instanceof Subquery ? gainSubqueryString((Subquery<T, M, L>) value)
				: (rawSQL != null ? rawSQL : gainValue(key, column, value)));
	}

	public String gainCompareString(String key, String column, Object value, String type, String rawSQL) throws Exception {
		if (value != null && JSON.isBoolOrNumOrStr(value) == false && value instanceof Subquery == false) {
			throw new IllegalArgumentException(key + ":value 中 value 不合法！比较运算 [>, <, >=, <=] 只支持 [Boolean, Number, String] 内的类型 ！");
		}

		String rc = column.endsWith("[") || column.endsWith("{") ? column.substring(0, column.length() - 1) : column;
		if ( ! StringUtil.isName(rc)) {
			throw new IllegalArgumentException(key + ":value 中 key 不合法！比较运算 [>, <, >=, <=] 不支持 [&, !, |] 中任何逻辑运算符 ！");
		}

		return gainKey(column) + " " + type + " " + (value instanceof Subquery ? gainSubqueryString((Subquery<T, M, L>) value)

View on GitHub (pinned to 5284052872)

Solutions

  1. Use only valid column names in keys; strip stray operators.
  2. Express AND/OR via @combine, not via symbols inside the key.
  3. Express NOT with the trailing '!' suffix only: "key!": value; use length via "key[" and json_length via "key{".

Example fix

// before
{"User": {"name&": "az"}}
// after
{"User": {"name": "az", "@combine": "name & tag"}}
Defensive patterns

Strategy: validation

Validate before calling

function isName(s) { return /^[A-Za-z_$][\w$]*(\.[A-Za-z_$][\w$]*)*$/.test(s); }
function validEqKey(key) {
  let k = key.endsWith('!') ? key.slice(0, -1) : key;
  k = k.endsWith('[') || k.endsWith('{') ? k.slice(0, -1) : k;
  return isName(k);
}
if (!validEqKey(condKey)) throw new Error('bad column key ' + condKey);

Prevention

When it happens

Trigger: A condition key like "name&", "col|other", "a.b.c!" or any key whose base part is not a valid identifier (letters, digits, '_', '$', and dot-separated parts per isName rules).

Common situations: Trying to express AND/OR logic by gluing operators onto the key ("price&>10" style), malformed dynamic keys built client-side, or keys containing SQL meta-characters.

Related errors

AI-assisted analysis of Tencent/APIJSON@5284052872 (2026-08-14). Data as JSON: /api/errors/a69892cb65e4a0c3. Report an issue: GitHub.