Tencent/APIJSON · error · IllegalArgumentException

{method}请求，{name}/{key} 里面的 {idKey}:value 中value的类型只能是 Long

Error message

{method}请求，{name}/{key} 里面的 {idKey}:value 中value的类型只能是 Long 或 String ！

What it means

Thrown by AbstractVerifier.verifyId (APIJSON ORM) when a single-record write request (PUT/DELETE) supplies an id whose runtime type is neither Number nor String. The verifier only accepts numeric Long-style ids or string ids so it can safely generate the WHERE id = ? condition without type ambiguity.

Source

Thrown at APIJSONORM/src/main/java/apijson/orm/AbstractVerifier.java:750

		});

	}

	/**
	 * @param method
	 * @param name
	 * @param key
	 * @param robj
	 * @param idKey
	 * @param atLeastOne 至少有一个不为null
	 */
	private static <T, M extends Map<String, Object>, L extends List<Object>> void verifyId(
			@NotNull String method, @NotNull String name, @NotNull String key
			, @NotNull M robj, @NotNull String idKey, final int maxUpdateCount, boolean atLeastOne) throws Exception {
		//单个修改或删除
		Object id = robj.get(idKey); //如果必须传 id ，可在Request表中配置NECESSARY
		if (id != null && id instanceof Number == false && id instanceof String == false) {
			throw new IllegalArgumentException(method + "请求，" + name + "/" + key
					+ " 里面的 " + idKey + ":value 中value的类型只能是 Long 或 String ！");
		}


		//批量修改或删除
		String idInKey = idKey + "{}";
		// id引用, 格式: "id{}@": "sql"
		String idRefInKey = getString(robj, idKey + "{}@");
		L idIn = null;
		try {
			idIn = get(robj, idInKey); //如果必须传 id{} ，可在Request表中配置NECESSARY
		} catch (Exception e) {
			throw new IllegalArgumentException(method + "请求，" + name + "/" + key
					+ " 里面的 " + idInKey + ":value 中value的类型只能是 [Long] ！");
		}
		if (idIn == null) {
			if (atLeastOne && id == null && idRefInKey == null) {
				throw new IllegalArgumentException(method + "请求，" + name + "/" + key

View on GitHub (pinned to 5284052872)

Solutions

Change the id value in the request to a Long (e.g. 82001) or a numeric/uuid String (e.g. "82001")
If the client DTO serializes id as an object, flatten it to a scalar before sending
Check middleware that may wrap or transform the id field

Example fix

// before
{"User":{"id":{"value":82001},"name":"a"}}
// after
{"User":{"id":82001,"name":"a"}}

Defensive patterns

Strategy: validation

Validate before calling

function assertIdType(obj, idKey = 'id') {
  const v = obj[idKey];
  if (v != null && typeof v !== 'number' && typeof v !== 'string') {
    throw new TypeError(`${idKey} must be a number or string, got ${typeof v}`);
  }
}

Type guard

const isIdValue = (v) => v == null || typeof v === 'number' || typeof v === 'string';

Try / catch

catch (e) { if (e instanceof IllegalArgumentException && /id.*Long 或 String/.test(e.message)) showFieldError('id'); else throw e; }

Prevention

Type the id field as number|string in client models
Run a shared pre-send sanitizer over every write body
Log the offending raw JSON body when this fires to find which field was malformed

When it happens

Trigger: A PUT/DELETE body like {"User":{"id":true}} or {"User":{"id":{} }} or {"User":{"id":[1]}} — i.e. robj.get(idKey) returns a Boolean, Map, or List instead of a Number/String.

Common situations: Client serializes a boolean flag or nested object into the id field; frontend sends id as a JSON object after a refactoring; a proxy/gateway rewrites id into an array; using a non-standard idKey whose value is a struct.

Related errors

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