apache/incubator-seata · error · IllegalArgumentException

{dataName} data is too large, size={length}

Error message

{dataName} data is too large, size={length}

What it means

Thrown by StringUtils.checkDataSize when a checked data field (e.g. transaction context, xid, or application metadata serialized into protocol messages) exceeds errorSize bytes when UTF-8 encoded, and throwIfErr is true. It exists to stop oversized payloads from corrupting or bloating protocol frames; below the threshold the method only logs a warning.

Source

Thrown at common/src/main/java/org/apache/seata/common/util/StringUtils.java:374

    /**
     * check string data size
     *
     * @param data the str
     * @param dataName the data name
     * @param errorSize throw exception if size > errorSize
     * @return boolean
     */
    public static boolean checkDataSize(String data, String dataName, int errorSize, boolean throwIfErr) {
        if (isBlank(data)) {
            return true;
        }
        int length = data.getBytes(StandardCharsets.UTF_8).length;
        if (length > errorSize) {
            LOGGER.warn("{} data is large(errorSize), size={}", dataName, length);
            if (!throwIfErr) {
                return false;
            }
            throw new IllegalArgumentException(dataName + " data is too large, size=" + length);
        }
        return true;
    }

    public static boolean hasLowerCase(String str) {
        if (null == str) {
            return false;
        }
        for (int i = 0; i < str.length(); i++) {
            if (Character.isLowerCase(str.charAt(i))) {
                return true;
            }
        }
        return false;
    }

    public static boolean hasUpperCase(String str) {
        if (null == str) {

View on GitHub (pinned to e01f97c6db)

Solutions

1. Shrink the offending field identified by dataName in the message (e.g. shorten applicationId, transaction group, or context keys).
2. If the data is legitimately large, move it out of the transaction metadata and reference it by ID instead.
3. Raise the configured limit only if you control both client and server and understand the frame-size impact.
4. Remember the check is on UTF-8 bytes, not characters — non-ASCII text counts 2-4x.

Example fix

// before: stuffing a whole payload into the action context
context.put("payload", hugeJsonString); // triggers checkDataSize failure

// after: pass a reference instead
String payloadId = payloadStore.save(hugeJsonString);
context.put("payloadId", payloadId);

boolean ok = StringUtils.checkDataSize(data, dataName, errorSize, false); // never throws
if (!ok) {
    // shrink, externalize, or reject the payload explicitly
}

try {
    StringUtils.checkDataSize(data, dataName, errorSize, true);
} catch (IllegalArgumentException e) {
    throw new BusinessException(dataName + " exceeds " + errorSize + " UTF-8 bytes", e);
}

When it happens

Trigger: Passing a String to checkDataSize(data, dataName, errorSize, true) whose UTF-8 byte length exceeds errorSize. Typical callers validate applicationId/transaction service group/xid or user context payloads before encoding them into Seata protocol messages.

Common situations: Very long transactionServiceGroup or application names; oversized xid produced by custom coordinators; large business data stuffed into BusinessActionContext; multi-byte (CJK) content inflating byte length beyond the character count a developer estimated.

Related errors

• could not convert '{size}' to byte length
• Unknown BranchType[{name}]
• TCC bean name cannot be null or empty
• not support config type:
• the {%s} can't be empty

AI-assisted analysis of apache/incubator-seata@e01f97c6db (2026-08-14). Data as JSON: /api/errors/4b00fe7ee106ff43. Report an issue: GitHub.