Tencent/APIJSON · error · IllegalArgumentException

join:${e.getKey()}' 对应的 ${tableKey}:{ ${key}: value } 中 valu

Error message

join:${e.getKey()}' 对应的 ${tableKey}:{ ${key}: value } 中 value 类型不合法！必须为同层级引用赋值路径 String！

What it means

When the join path names an explicit ON key (e.g. '@/Comment/toId@'), the joined table object must contain that key with a String value holding the same-layer reference-assignment path. This IllegalArgumentException is thrown when tableObj.get(key) is not a String (number, object, array, boolean, or null).

Source

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

					throw new IllegalArgumentException(apijson.JSONRequest.KEY_JOIN + ":'" + e.getKey() + "' 对应的 " + arrKey + ":{ page: value } 中 value 不合法！" +
							"@ APP JOIN 最多允许跨 1 层，只能是子数组，且数组对象中 page 值只能为 null 或 0 ！");
				}
			}

			boolean isAppJoin = "@".equals(joinType);

			M refObj = JSON.createJSONObject();

			String key = index < 0 ? null : path.substring(index + 1); // id@
			if (key != null) {  // 指定某个 key 为 JOIN ON 条件
				if (key.indexOf("@") != key.length() - 1) {
					throw new IllegalArgumentException(apijson.JSONRequest.KEY_JOIN + ":" + e.getKey() + " 中 " + key + " 不合法！"
							+ "必须为 &/Table0,</Table1/key1,@/Table1:alias2/key2,... 或 { '&/Table0':{}, '</Table1/key1':{},... } 这种格式！"
							+ "且 Table:alias 的 alias 必须满足英文单词变量名格式！");
				}

				if (tableObj.get(key) instanceof String == false) {
					throw new IllegalArgumentException(apijson.JSONRequest.KEY_JOIN + ":" + e.getKey() + "' 对应的 "
            			+ tableKey + ":{ " + key + ": value } 中 value 类型不合法！必须为同层级引用赋值路径 String！");
				}

				if (isAppJoin && StringUtil.isName(key.substring(0, key.length() - 1)) == false) {
					throw new IllegalArgumentException(apijson.JSONRequest.KEY_JOIN + ":'" + e.getKey() + "' 中 " + key + " 不合法 ！" +
							"@ APP JOIN 只允许 key@:/Table/refKey 这种 = 等价连接！");
				}

				refObj.put(key, getString(tableObj, key));
			}


			Set<Entry<String, Object>> tableSet = tableObj.entrySet();
			// 取出所有 join 条件
			M requestObj = JSON.createJSONObject(); // (Map<String, Object>) obj.clone();

			boolean matchSingle = false;
			for (Entry<String, Object> tableEntry : tableSet) {

View on GitHub (pinned to 5284052872)

Solutions

Change the value of the key@ entry inside the joined table object to a reference path String: 'toId@': '/User/id'
If you meant a literal value condition, keep it as a normal key ('toId': 38710) and do not name it in the join path

Example fix

// before
{ 'join': '@/Comment/toId@', 'Comment': { 'toId@': 38710 } }
// after
{ 'join': '@/Comment/toId@', 'Comment': { 'toId@': '/User/id' } }

Defensive patterns

Strategy: type-guard

Validate before calling

function checkOnValueTypes(req, joinValue) {
  const paths = typeof joinValue === 'string' ? [joinValue] : Object.keys(joinValue);
  for (const p of paths) {
    const rest = p.substring(p.indexOf('/') + 1);
    const parts = rest.split('/');
    const tableKey = parts[parts.length - 2], key = parts[parts.length - 1];
    const tbl = req[tableKey.split(':')[0]];
    if (key.endsWith('@') && tbl != null && typeof tbl[key] !== 'string') {
      return `${tableKey}.${key} must be a String reference path, got ${typeof tbl[key]}`;
    }
  }
  return null;
}

Type guard

const isRefPath = (v) => typeof v === 'string' && v.startsWith('/');

Try / catch

Catch IllegalArgumentException with '必须为同层级引用赋值路径 String'; point the user at the named key@ entry and coerce it to '/Table/key' form.

Prevention

key@ values are always Strings starting with '/', never literal ids
Keep literals under plain keys and reference paths under key@ keys

When it happens

Trigger: { 'join': '@/Comment/toId@', 'Comment': { 'toId@': 38710 } } — the ON key exists but its value is a literal id instead of a path String like '/User/id'; also 'toId@': { '/User/id': {} } or a missing/null value.

Common situations: Writing the actual column value where the reference path is expected; mixing up which side of the join holds the path; converting an existing WHERE condition into a join without changing the value format.

Related errors

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