Tencent/APIJSON · error · UnsupportedDataTypeException

{key}:value 的 value 不合法！类型必须是 ARRAY ，结构为 [] !

Error message

{key}:value 的 value 不合法！类型必须是 ARRAY ，结构为 [] !

What it means

Thrown during template-value merge in verify: the target (Request-table template) declares a key whose value is an ARRAY ([]), but the client sent a non-array (scalar or object). The request must match the template's shape.

Source

Thrown at APIJSONORM/src/main/java/apijson/orm/AbstractVerifier.java:1024

				}
				if (rvalue != null && trimKeyList != null && trimKeyList.contains(key)) {
					rvalue = StringUtil.trim(rvalue);
				}

				if (callback.onParse(key, tvalue, rvalue) == false) {
					continue;
				}

				if (tvalue instanceof Map<?, ?>) { // JSONRequest，往下一级提取
					if (rvalue != null && rvalue instanceof Map<?, ?> == false) {
						throw new UnsupportedDataTypeException(key + ":value 的 value 不合法！类型必须是 OBJECT ，结构为 {} !");
					}
					tvalue = callback.onParseJSONObject(key, (M) tvalue, (M) rvalue);

					objKeySet.add(key);
				} else if (tvalue instanceof List<?>) { // L
					if (rvalue != null && rvalue instanceof List<?> == false) {
						throw new UnsupportedDataTypeException(key + ":value 的 value 不合法！类型必须是 ARRAY ，结构为 [] !");
					}
					tvalue = callback.onParseJSONArray(key, (L) tvalue, (L) rvalue);

					if ((method == POST || method == PUT) && isArrayKey(key)) {
						objKeySet.add(key);
					}
				} else { // 其它Object
					tvalue = callback.onParseObject(key, tvalue, rvalue);
				}

				if (tvalue != null) { // 可以在target中加上一些不需要客户端传的键值对
					real.put(key, tvalue);
				}
			}

		}

		// 解析内容>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>

View on GitHub (pinned to 5284052872)

Solutions

1. Send the value as a JSON array: {"tag":["a"]}
2. Fix client serialization so arrays stay arrays (correct Content-Type: application/json)
3. If scalars are intended, update the template value to a scalar

Example fix

// before
{"User":{"tag":"a"}}
// after
{"User":{"tag":["a"]}}

function assertShape(value, template) {
  for (const k of Object.keys(template)) {
    const t = template[k], v = value[k];
    if (v != null && Array.isArray(t) && !Array.isArray(v)) {
      throw new TypeError(`${k} must be an array per template`);
    }
  }
}

const isArrayOrNull = (v) => v == null || Array.isArray(v);

When it happens

Trigger: Template has "User":{"tag":[]} but the client sends {"User":{"tag":"a"}} or {"User":{"tag":{"0":"a"}}} — rvalue is not a List while tvalue is.

Common situations: Client JSON-encodes an array into a string; a form encoder turns [] into an object with numeric keys; template authored with [] as placeholder while clients send single values.

Related errors

• {key}:value 的 value 不合法！类型必须是 OBJECT ，结构为 {} !
• 远程函数 " + methodName + " 的实际返回值类型 " + (rt == null ? null : rt
• {}/{}:{} 不合法！数组 []:{} 中第一个 key:{} 必须是主表 TableKey:{} ！不能为 arr
• {} 内截至 {}:{} 时数组对象 key[]:{} 的数量达到 {} 已超限，必须在 0-{} 内 !
• {}/{}:{} 不合法！数组 []:{} 中每个 key:{} 都必须是表 TableKey:{} 或 数组 arra

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