Tencent/APIJSON · error · IllegalArgumentException

${e.getKey()}:'/targetTable:targetAlias/targetKey' 中 targetA

Error message

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

What it means

A reference path may address a table through an alias ('/targetTable:targetAlias/targetKey'). The alias part is optional, but if present it must satisfy StringUtil.isName. This IllegalArgumentException fires when a non-empty alias contains invalid identifier characters.

Source

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

				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 + " 不合法！必须满足英文单词变量名格式！");
				}

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

				//对引用的JSONObject添加条件
				Map<String, Object> targetObj;
				try {
					targetObj = JSON.get(request, targetTableKey);
				}
				catch (Exception e2) {
					throw new IllegalArgumentException(e.getKey() + ":'/targetTable/targetKey' 中路径对应的 '" + targetTableKey + "':value 中 value 类型不合法！必须是 {} 这种 Map<String, Object> 格式！" + e2.getMessage());
				}

				if (targetObj == null) {
					throw new IllegalArgumentException(e.getKey() + ":'/targetTable/targetKey' 中路径对应的对象 '" + targetTableKey + "':{} 不存在或值为 null ！必须是 {} 这种 Map<String, Object> 格式！");

View on GitHub (pinned to 5284052872)

Solutions

Change the alias to a plain identifier: '/User:owner/id'
Drop the alias if the default (table-name) reference is sufficient: '/User/id'

Example fix

// before
{ 'join': '</Comment', 'Comment': { 'userId@': '/User:my user/id' } }
// after
{ 'join': '</Comment', 'Comment': { 'userId@': '/User:owner/id' } }

Defensive patterns

Strategy: validation

Validate before calling

const NAME_RE = /^[A-Za-z_][A-Za-z0-9_]*$/;
function checkRefAliases(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 seg = v.split('/')[1];
        const alias = seg.includes(':') ? seg.split(':')[1] : null;
        if (alias != null && alias !== '' && !NAME_RE.test(alias)) return `${k}: alias '${alias}' is not a valid identifier`;
      }
    }
  }
  return null;
}

Type guard

const isValidAlias = (a) => a == null || /^[A-Za-z_][A-Za-z0-9_]*$/.test(a);

Try / catch

Catch IllegalArgumentException containing 'targetAlias 值'; replace the alias with a plain identifier or drop it.

Prevention

Aliases in reference paths are plain identifiers — no spaces, hyphens, digits-first, or extra ':'
Reuse the same alias everywhere: join path, table object key, and ON reference path

When it happens

Trigger: 'userId@': '/User:my user/id' (space), '/User:u-1/id' (hyphen), '/User:1owner/id' (starts with digit), '/User:owner:extra/id' (double colon).

Common situations: Using display labels or SQL expressions as alias; alias values generated from user input or i18n strings; misunderstanding that ':' separates exactly one table:alias pair.

Related errors

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