Tencent/APIJSON · error · IllegalArgumentException

@cache:value 中 value 的值不合法！必须在 [0,1,2] 或 [ALL, ROM, RAM] 内 !

Error message

@cache:value 中 value 的值不合法！必须在 [0,1,2] 或 [ALL, ROM, RAM] 内 !

What it means

getCache() maps the @cache value to an int via a switch; only 0/1/2 and ALL/ROM/RAM (case-sensitive, JSONMap.CACHE_*_STRING constants) are accepted. Any other string hits the default branch and throws IllegalArgumentException. @cache controls whether query results may be served from or stored in the all/rom/ram cache layer.

Source

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

			//			if (isSubquery) {
			//				throw new IllegalArgumentException("子查询内不支持传 " + apijson.JSONMap.KEY_CACHE + "!");
			//			}

			switch (cache) {
			case "0":
			case JSONMap.CACHE_ALL_STRING:
				cache2 = JSONMap.CACHE_ALL;
				break;
			case "1":
			case JSONMap.CACHE_ROM_STRING:
				cache2 = JSONMap.CACHE_ROM;
				break;
			case "2":
			case JSONMap.CACHE_RAM_STRING:
				cache2 = JSONMap.CACHE_RAM;
				break;
			default:
				throw new IllegalArgumentException(JSONMap.KEY_CACHE
						+ ":value 中 value 的值不合法！必须在 [0,1,2] 或 [ALL, ROM, RAM] 内 !");
			}
		}
		return cache2;
	}

	@Override
	public boolean isExplain() {
		return explain;
	}
	@Override
	public AbstractSQLConfig<T, M, L> setExplain(boolean explain) {
		this.explain = explain;
		return this;
	}

	@Override
	public List<Join<T, M, L>> getJoinList() {

View on GitHub (pinned to 5284052872)

Solutions

1. Use exactly 0|1|2 or ALL|ROM|RAM, uppercase, no whitespace: {"@cache":"RAM"}.
2. If the value comes from user input or config, normalize it (trim + toUpperCase) and check membership before sending the request.
3. Default to omitting @cache entirely when caching is not needed — the field is optional.

Example fix

// before
{"@cache":"ram","User":{"id":1}}
// after
{"@cache":"RAM","User":{"id":1}}

Set<String> CACHE = Set.of("0","1","2","ALL","ROM","RAM");
String v = String.valueOf(request.get("@cache")).strip().toUpperCase();
if (!CACHE.contains(v)) request.put("@cache", "ALL"); // or reject

function isValidCache(v: unknown): v is string {
  return ["0","1","2","ALL","ROM","RAM"].includes(String(v).trim().toUpperCase());
}

When it happens

Trigger: A request like {"@cache":"ram", "User":{...}} (lowercase), {"@cache":3}, {"@cache":" ROM "}, or {"@cache":true}. The switch is over strings, so numeric values other than "0"/"1"/"2" and any whitespace/case variant of ALL/ROM/RAM fail.

Common situations: Assuming @cache is case-insensitive; passing a boolean because other APIJSON flags accept true/false; trailing whitespace from template-built request JSON; version drift where older docs listed different cache keywords.

Related errors

• {errPrefix} 中字符 '{key}' 对应的条件键值对 {column}:value 不存在！
• {errPrefix} 中字符 '{key}' 对应的 {column}:value 不是有效条件键值对！
• Value for key '" + key + "' is not a Map: " + value.getClass
• Value for key '" + key + "' is not a List: " + value.getClas
• Cannot convert String value '" + value + "' to int: " + e.ge

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