What causes "{}:{ @combine:'{}' } 中字符 '{}' 不合法！括号 (()) 嵌套层级 {} 已超过最大值，必须在 0-{} 内！" in Tencent/APIJSON?

Flatten the @combine expression to fewer nesting levels (use distributive rewriting like a&(b|c) => (a&b)|(a&c) only when needed; usually just reduce grouping).

Tencent/APIJSON · error · IllegalArgumentException

{}:{ @combine:'{}' } 中字符 '{}' 不合法！括号 (()) 嵌套层级 {} 已超过最大值，必须在

Error message

{}:{ @combine:'{}' } 中字符 '{}' 不合法！括号 (()) 嵌套层级 {} 已超过最大值，必须在 0-{} 内！

What it means

Thrown while parsing @combine when the parenthesis nesting depth exceeds the configured maximum (maxDepth). Each '(' increments depth; if depth becomes greater than maxDepth (and maxDepth > 0) the parser stops and rejects the expression to bound recursion/complexity of the generated WHERE clause.

Source

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

					}
					else if (last <= 0 || last == ' ' || last == '(') {
						isNot = true;
						//					lastLogic = c;
					}
					else {
						key += c;
					}
				}
				else if (c == '(') {
					if (key.isEmpty() == false || (i > 0 && lastLogic <= 0 && last != '(')) {
						throw new IllegalArgumentException(errPrefix + " 中字符 '" + s.substring(i)
						+ "' 不合法！左边缺少 & | 逻辑连接符！逻辑连接符 & | 左右必须各一个相邻空格！空格不能多也不能少！"
						+ "不允许首尾有空格，也不允许连续空格！左括号 ( 的右边 和 右括号 ) 的左边 都不允许有相邻空格！");
					}

					depth ++;
					if (depth > maxDepth && maxDepth > 0) {
						throw new IllegalArgumentException(errPrefix + " 中字符 '" + s.substring(0, i + 1)
						+ "' 不合法！括号 (()) 嵌套层级 " + depth + " 已超过最大值，必须在 0-" + maxDepth + " 内！");
					}

					result += c;
					lastLogic = 0;
					first = true;
				}
				else if (c == ')') {
					depth --;
					if (depth < 0) {
						throw new IllegalArgumentException(errPrefix + " 中字符 '" + s.substring(0, i + 1)
						+ "' 不合法！左括号 ( 比 右括号 ) 少！数量必须相等从而完整闭合 (...) ！");
					}

					result += c;
					lastLogic = 0;
				}
				else {

View on GitHub (pinned to 5284052872)

Solutions

Flatten the @combine expression to fewer nesting levels (use distributive rewriting like a&(b|c) => (a&b)|(a&c) only when needed; usually just reduce grouping).
Raise the max query depth configuration if your deployment genuinely needs deeper nesting.
Move deep grouping logic into a server-side custom API or view instead of @combine.

Example fix

// before
{"@combine": "((a & b) | (c & (d | e))) & f"}
// after
{"@combine": "(a & b) | (c & d) | (c & e)"}

Defensive patterns

Strategy: validation

Validate before calling

function combineDepth(s) {
  let d = 0, max = 0;
  for (const ch of s) { if (ch === '(') max = Math.max(max, ++d); if (ch === ')') d--; }
  return max;
}
// reject before sending
if (combineDepth(combineStr) > 2) throw new Error('combine nesting too deep');

Try / catch

try { await apijson.put(req); } catch (e) { if (/嵌套层级/.test(e.message)) flattenCombine(); else throw e; }

Prevention

Cap nesting at 2 levels in UI query builders.
Check depth client-side with a parenthesis counter before each request.
Prefer splitting very complex filtering into multiple requests or a custom API.

When it happens

Trigger: A @combine value with more than the allowed nested parentheses, e.g. "((a & b) | (c & (d | e)))" when maxDepth is limited to 2 or the default MAX_QUERY_DEPTH.

Common situations: Complex multi-group filtering built dynamically by a frontend that nests groups deeper than the server allows; default depth limits changing between APIJSON versions.

Related errors

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