Tencent/APIJSON · error · IllegalArgumentException

${e.getKey()}:value 中 value 值 ${targetPath} 不合法！必须为引用赋值的路径 '

Error message

${e.getKey()}:value 中 value 值 ${targetPath} 不合法！必须为引用赋值的路径 '/targetTable/targetKey' ！

What it means

For each ON condition, the value of the 'key@' entry must be a non-empty reference path like '/targetTable/targetKey'. This IllegalArgumentException is thrown when that value is empty or whitespace-only (StringUtil.isEmpty(targetPath, true)).

Source

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

            if (whereJoinMap.containsKey(table)) {
                Object rawOuter = whereJoinMap.get(table);
                M outerObj1 = (M) JSON.createJSONObject((Map<String, Object>) rawOuter);
                j.setOuter(outerObj1);
            }

			if (arrKey != null) {
				Integer count = getInteger(parentPathObj, apijson.JSONRequest.KEY_COUNT);
				j.setCount(count == null ? getDefaultQueryCount() : count);
			}

			List<Join.On> onList = new ArrayList<>();
			for (Entry<String, Object> refEntry : refSet) {
				String originKey = refEntry.getKey();

				String targetPath = (String) refEntry.getValue();
				if (StringUtil.isEmpty(targetPath, true)) {
					throw new IllegalArgumentException(e.getKey() + ":value 中 value 值 " + targetPath + " 不合法！必须为引用赋值的路径 '/targetTable/targetKey' ！");
				}

				// 取出引用赋值路径 targetPath 对应的 Table 和 key
				index = targetPath.lastIndexOf("/");
				String targetKey = index < 0 ? null : targetPath.substring(index + 1);
				if (StringUtil.isName(targetKey) == false) {
					throw new IllegalArgumentException(e.getKey() + ":'/targetTable/targetKey' 中 targetKey 值 " + targetKey + " 不合法！必须满足英文单词变量名格式！");
				}

				targetPath = targetPath.substring(0, index);
				index = targetPath.lastIndexOf("/");
				String targetTableKey = index < 0 ? targetPath : targetPath.substring(index + 1);

				// 主表允许别名
				apijson.orm.Entry<String, String> targetEntry = Pair.parseEntry(targetTableKey, true);
				String targetTable = targetEntry.getKey(); //User
				if (StringUtil.isName(targetTable) == false) {
					throw new IllegalArgumentException(e.getKey() + ":'/targetTable/targetKey' 中 targetTable 值 " + targetTable + " 不合法！必须满足大写字母开头的表对象英文单词 key 格式！");

View on GitHub (pinned to 5284052872)

Solutions

Fill in the reference path: 'userId@': '/User/id'
Remove the empty key@ entry entirely if no join condition is intended (but note a join then needs '*' type or another ON key)

Example fix

// before
{ 'join': '</Moment', 'Moment': { 'userId@': '' } }
// after
{ 'join': '</Moment', 'Moment': { 'userId@': '/User/id' }, 'User': { 'id': 38710 } }

Defensive patterns

Strategy: validation

Validate before calling

function checkEmptyRefs(req) {
  for (const [tblKey, tbl] of Object.entries(req)) {
    if (tbl && typeof tbl === 'object') {
      for (const [k, v] of Object.entries(tbl)) {
        if (k.endsWith('@') && (v == null || String(v).trim() === '')) {
          return `${tblKey}/${k} is empty; reference paths must look like '/Table/key'`;
        }
      }
    }
  }
  return null;
}

Type guard

const isNonEmptyRefPath = (v) => typeof v === 'string' && v.trim().length > 0 && v.startsWith('/');

Try / catch

Catch IllegalArgumentException with "必须为引用赋值的路径"; fill or strip the empty key@ entry.

Prevention

Reject empty/whitespace values in key@ fields at form-validation time
Treat blank reference fields as bugs in the request builder, not as optional

When it happens

Trigger: { 'join': '</Moment', 'Moment': { 'userId@': '' } } or 'userId@': ' ' — the reference key exists but points at nothing.

Common situations: Building the request from a form/template where the reference field was left blank; stripping a value during sanitization; copy-paste of an unfinished example.

Related errors

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