Tencent/APIJSON · error · IllegalArgumentException

${e.getKey()}:'/targetTable/targetKey' 中 targetKey 值 ${targe

Error message

${e.getKey()}:'/targetTable/targetKey' 中 targetKey 值 ${targetKey} 不合法！必须满足英文单词变量名格式！

What it means

The last segment of a reference path ('/targetTable/targetKey') is the target key and must satisfy StringUtil.isName. This IllegalArgumentException fires when targetKey is not a valid identifier — including the empty string when the path ends with '/', or null when the path has no '/' at all.

Source

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

			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 格式！");
				}

				String targetAlias = targetEntry.getValue(); //owner
				if (StringUtil.isNotEmpty(targetAlias, true) && StringUtil.isName(targetAlias) == false) {
					throw new IllegalArgumentException(e.getKey() + ":'/targetTable:targetAlias/targetKey' 中 targetAlias 值 " + targetAlias + " 不合法！必须满足英文单词变量名格式！");
				}

View on GitHub (pinned to 5284052872)

Solutions

Fix the path to end with a valid identifier key: '/User/id'
Remove trailing slashes and any '()' function suffixes from reference paths used in joins

Example fix

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

Defensive patterns

Strategy: validation

Validate before calling

const NAME_RE = /^[A-Za-z_][A-Za-z0-9_]*$/;
function checkRefTargets(req) {
  for (const tbl of Object.values(req)) {
    if (tbl && typeof tbl === 'object') {
      for (const [k, v] of Object.entries(tbl)) {
        if (!k.endsWith('@') || typeof v !== 'string') continue;
        const key = v.substring(v.lastIndexOf('/') + 1);
        if (!NAME_RE.test(key)) return `${k}: targetKey '${key}' in '${v}' is not a valid identifier`;
      }
    }
  }
  return null;
}

Type guard

const isValidTargetKey = (p) => /^[A-Za-z_][A-Za-z0-9_]*$/.test(p.substring(p.lastIndexOf('/') + 1));

Try / catch

Catch IllegalArgumentException containing 'targetKey 值'; fix/strip the malformed trailing path segment.

Prevention

Reference paths end with a clean identifier — no trailing '/', no '()' suffixes
Unit-test path builders against NAME_RE for both table and key segments

When it happens

Trigger: 'userId@': '/User/' (trailing slash -> empty targetKey), '/User/id()' (function-call suffix), '/User/user id' (space), or 'userId@': 'Userid' with no slash at all.

Common situations: Trailing slash typos; pasting remote-function keys ('fn()') into join paths; key names with spaces or punctuation copied from a spreadsheet.

Related errors

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