Tencent/APIJSON · error · IllegalArgumentException

{}:value 中value不合法！非PUT请求只支持 [Boolean, Number, String] 内的类型

Error message

{}:value 中value不合法！非PUT请求只支持 [Boolean, Number, String] 内的类型 ！

What it means

Thrown by gainEqualString when the value used in an '='/'IS' condition is not a Boolean, Number, or String and is not a Subquery. Non-PUT requests only allow scalar types for equality, so JSONObject/JSONArray/Map values are rejected before SQL generation.

Source

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

		case 6:
			return gainContainString(key, column, value, rawSQL);
		case 7:
			return gainCompareString(key, column, value, ">=", rawSQL);
		case 8:
			return gainCompareString(key, column, value, "<=", rawSQL);
		case 9:
			return gainCompareString(key, column, value, ">", rawSQL);
		case 10:
			return gainCompareString(key, column, value, "<", rawSQL);
		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 {

View on GitHub (pinned to 5284052872)

Solutions

For matching against multiple values use the {} operator: "tag{}": [1,2,3].
For a single value, send a plain Boolean/Number/String.
For JSON-typed columns, use the appropriate key suffix (key$ / key{}) or raw SQL rather than a nested object value.

Example fix

// before
{"User": {"id": [1, 2]}}
// after
{"User": {"id{}": [1, 2]}}

Defensive patterns

Strategy: type-guard

Validate before calling

const isScalar = v => v === null || ['boolean','number','string'].includes(typeof v);
for (const [k, v] of Object.entries(tableObj)) {
  if (k.startsWith('@') || /[{}$~<>%]|!$|\[$|\{$/.test(k)) continue;
  if (!isScalar(v)) throw new Error(`key ${k} needs a scalar or key{} for arrays`);
}

Type guard

function isBoolOrNumOrStr(v) { return typeof v === 'boolean' || typeof v === 'number' || typeof v === 'string'; }

Prevention

Use key{} for arrays/maps, plain key only for scalars.
Run a request-linter that flags non-scalar values on non-PUT equality keys.

When it happens

Trigger: Sending {"User": {"tag": [1,2,3]}} (use "tag{}" for matching arrays) or {"info": {"a":1}} with a GET/DELETE method, where value arrives as a collection/map.

Common situations: Confusing '=' with the IN/match operator: developers send arrays to key instead of key{}; sending JSON objects where the column expects a scalar.

Related errors

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