Tencent/APIJSON · error · IllegalArgumentException

puts StringUtil.isEmpty(key, true)…

Error message

puts  StringUtil.isEmpty(key, true) clazz.getAnnotation(MethodAccess.class) == null \n key为空时仅支持 类型被@MethodAccess注解 的value !!! \n 如果一定要这么用，请对 " + clazz.getName() + " 注解！ \n 如果是类似 key[]:{} 结构的请求，建议用 putsAll(...) ！

What it means

JSONMap.put(Object value) is a convenience overload that derives the key from the value's class simple name, but it only accepts classes annotated with @MethodAccess (APIJSON's per-class CRUD permission annotation). If the runtime class lacks the annotation, the library throws IllegalArgumentException listing the class and suggesting puts(key, value) or putsAll(...).

Solutions

Annotate the value class with @MethodAccess (e.g. @MethodAccess(GET=true, POST=true)) like other APIJSON models.
Or use the explicit-key overload puts("User", value) which bypasses the annotation check.
For array-style requests key[]:{} use putsAll(...) as the message suggests.
If the class is not under your control, wrap it in your own annotated wrapper class.

Example fix

// before
public class User { ... }
request.puts(new User()); // throws

// after
@MethodAccess(POST = true, GET = true)
public class User { ... }
request.puts(new User());

Defensive patterns

Strategy: validation

Validate before calling

if (value.getClass().getAnnotation(MethodAccess.class) == null) {
    map.puts(value.getClass().getSimpleName(), value); // explicit key bypasses the check
}

Type guard

public static <T> boolean isMethodAccessAnnotated(Class<T> clazz) {
    return clazz.getAnnotation(MethodAccess.class) != null;
}

Try / catch

try { request.puts(value); } catch (IllegalArgumentException e) { request.puts(value.getClass().getSimpleName(), value); }

Prevention

Copy @MethodAccess onto every model used in puts(Object) — treat it as part of the class template.
Prefer puts(key, value) for third-party classes you cannot annotate.
Add a startup check that scans request model packages for missing @MethodAccess.

When it happens

Trigger: Calling puts(value) or put(value) on a JSONMap/JSONObjectRequest with a POJO whose class is not annotated with @MethodAccess.

Common situations: New DTO added to a request without copying the @MethodAccess annotation from existing models; using third-party or java.* classes as values; refactoring renamed the class and the annotation was lost.

Related errors

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

Appendix: source

Thrown at APIJSONORM/src/main/java/apijson/JSONMap.java:681

		return this;
	}
	/**put and return this
	 * @param key
	 * @param value 
	 * @return this
	 */
	default JSONMap<M, L> puts(String key, Object value) {
		put(key, value);
		return this;
	}

	/**put and return value
	 * @param value  must be annotated by {@link MethodAccess}
	 */
	default Object put(Object value) {
		Class<?> clazz = value.getClass(); //should not return null
		if (clazz.getAnnotation(MethodAccess.class) == null) {
			throw new IllegalArgumentException("puts  StringUtil.isEmpty(key, true)" +
					" clazz.getAnnotation(MethodAccess.class) == null" +
					" \n key为空时仅支持 类型被@MethodAccess注解 的value !!!" +
					" \n 如果一定要这么用，请对 " + clazz.getName() + " 注解！" +
					" \n 如果是类似 key[]:{} 结构的请求，建议用 putsAll(...) ！");
		}
		return put(clazz.getSimpleName(), value);
	}

	/**puts key-value in object into this
	 * @param map
	 * @return this
	 */
	default JSONMap<M, L> putsAll(Map<? extends String, ? extends Object> map) {
		putAll(map);
		return this;
	}

View on GitHub (pinned to 5284052872)