Tencent/APIJSON · error · IllegalArgumentException

/query:value 中 value 的值不合法！必须在 [0, 1, 2] 或 [TABLE, TOTAL…

Error message

{}/query:value 中 value 的值不合法！必须在 [0, 1, 2] 或 [TABLE, TOTAL, ALL] 内 !

What it means

Inside []:{}, the query parameter selects what to fetch. Only 0/TABLE, 1/TOTAL, 2/ALL (or their string names) are accepted; the switch's default branch throws IllegalArgumentException naming the path and the allowed sets. query2 is then used to decide whether to also fetch the total count.

Solutions

Set query to 0/TABLE, 1/TOTAL, or 2/ALL exactly as documented
If you need both rows and total, use query:2 (ALL)
Validate the value client-side against the enum before sending
Check the APIJSON version's JSONRequest constants for the exact accepted spellings

Example fix

// before
{"[]":{"query":"TABLES","User":{}}}
// after
{"[]":{"query":2,"User":{}}}

Defensive patterns

Strategy: validation

Validate before calling

Set<Object> OK = Set.of(0,1,2,"0","1","2","TABLE","TOTAL","ALL");
if (!OK.contains(query)) throw new IllegalArgumentException("bad query: " + query);

Type guard

boolean isValidQueryValue(Object q) {
  return q == null || Set.of(0,1,2,"TABLE","TOTAL","ALL").contains(q);
}

Prevention

Expose query as an enum client-side so invalid values cannot be constructed
Pin the accepted spellings from JSONRequest constants of your deployed version
Omit query entirely when default TABLE behavior suffices

When it happens

Trigger: {"[]":{"query":3,...}} or query:"TOTALS"/"tables"/true/1.0 — anything outside 0,1,2 and TABLE,TOTAL,ALL (case per constants). Sending query as a non-matching string hits default.

Common situations: Typos or pluralized names; using an integer as string with decimals; copying query from another framework's dialect; version change where new modes were expected but the deployed jar is older.

Related errors

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

Appendix: source

Thrown at APIJSONORM/src/main/java/apijson/orm/AbstractParser.java:1363

		if (query == null) {
			query2 = apijson.JSONRequest.QUERY_TABLE;
		}
		else {
			switch (query) {
			case "0":
			case apijson.JSONRequest.QUERY_TABLE_STRING:
				query2 = apijson.JSONRequest.QUERY_TABLE;
				break;
			case "1":
			case apijson.JSONRequest.QUERY_TOTAL_STRING:
				query2 = apijson.JSONRequest.QUERY_TOTAL;
				break;
			case "2":
			case apijson.JSONRequest.QUERY_ALL_STRING:
				query2 = apijson.JSONRequest.QUERY_ALL;
				break;
			default:
				throw new IllegalArgumentException(path + "/" + apijson.JSONRequest.KEY_QUERY + ":value 中 value 的值不合法！必须在 [0, 1, 2] 或 [TABLE, TOTAL, ALL] 内 !");
			}
		}

		int minPage = getMinQueryPage(); // 兼容各种传 0 或 null/undefined 自动转 0 导致的问题
		int page2 = page == null || page == 0 ? 0 : page - minPage;

		int maxPage = getMaxQueryPage();
		if (page2 < 0 || page2 > maxPage) {
			throw new IllegalArgumentException(path + "/" + apijson.JSONRequest.KEY_PAGE + ":value 中 value 的值不合法！必须在 " + minPage + "-" + maxPage + " 内 !");
		}

		//不用total限制数量了，只用中断机制，total只在query = 1,2的时候才获取
		int count2 = isSubquery || count != null ? (count == null ? 0 : count) : getDefaultQueryCount();
		int max = isSubquery ? count2 : getMaxQueryCount();

		if (count2 < 0 || count2 > max) {
			throw new IllegalArgumentException(path + "/" + apijson.JSONRequest.KEY_COUNT + ":value 中 value 的值不合法！必须在 0-" + max + " 内 !");
		}

View on GitHub (pinned to 5284052872)