flowable/flowable-engine · error · FlowableIllegalArgumentException

The length of the ${variableType.getTypeName()} value exceed

Error message

The length of the ${variableType.getTypeName()} value exceeds the maximum allowed length of ${maxAllowedLength} characters. Current length: ${length}, for variable: ${valueFields.getName()} in scope ${scopeType} with id ${scopeId}

What it means

Thrown when verifyLength detects a variable value longer than the configured maxAllowedLength. The message names the variable type, limit, actual length, variable name, scope type and scope id. This prevents silent truncation or DB errors when persisting oversized variable values (e.g. text longer than the VARCHAR column).

Source

Thrown at modules/flowable-engine-common/src/main/java/org/flowable/common/engine/impl/variable/MaxAllowedLengthVariableVerifier.java:50

        this.maxAllowedLength = maxAllowedLength;
    }

    @Override
    public void verifyLength(int length, ValueFields valueFields, VariableType variableType) {
        if (length > maxAllowedLength) {
            String scopeId;
            String scopeType;
            if (StringUtils.isNotEmpty(valueFields.getTaskId())) {
                scopeId = valueFields.getTaskId();
                scopeType = ScopeTypes.TASK;
            } else if (StringUtils.isNotEmpty(valueFields.getProcessInstanceId())) {
                scopeId = valueFields.getProcessInstanceId();
                scopeType = ScopeTypes.BPMN;
            } else {
                scopeId = valueFields.getScopeId();
                scopeType = valueFields.getScopeType();
            }
            throw new FlowableIllegalArgumentException(
                    "The length of the " + variableType.getTypeName() + " value exceeds the maximum allowed length of " + maxAllowedLength
                            + " characters. Current length: " + length
                            + ", for variable: " + valueFields.getName() + " in scope " + scopeType + " with id " + scopeId);
        }
    }

}

View on GitHub (pinned to d6d39ce1c6)

Solutions

1. Shorten the variable value (trim, compress, or split it)
2. Store large payloads as a file/content reference or use a different variable type (e.g. ByteArray/blobs with appropriate column sizes)
3. Increase the DB column size (e.g. ACT_GE_BYTEARRAY / ACT_RU_VARIABLE TEXT column) and the verifier limit accordingly
4. Adjust the configured maxAllowedLength to match the actual column capacity

Example fix

// before
runtimeService.setVariable(taskId, "payload", hugeJsonString); // 9000 chars, limit 4001
// after
runtimeService.setVariable(taskId, "payloadRef", fileStore.save(hugeJsonString)); // store reference instead

if (value != null && value.length() > 4001) {
    throw new IllegalArgumentException("variable value too long: " + value.length());
}

boolean withinLimit(String s, int max) {
    return s == null || s.length() <= max;
}

try {
    runtimeService.setVariable(scopeId, name, value);
} catch (FlowableIllegalArgumentException e) {
    if (e.getMessage().contains("exceeds the maximum allowed length")) {
        runtimeService.setVariable(scopeId, name, storeExternally(value));
    }
}

When it happens

Trigger: Setting a process/case/task variable whose serialized value length exceeds maxAllowedLength — e.g. storing a long string, JSON, or serialized Java object in a column-limited DB.

Common situations: Large payloads stored as string variables instead of files; long JSON documents; DB migration to a column with smaller capacity; user-generated content exceeding the 4001-char typical limit.

Understand the failure class

Background: "value must be between 0 and 1" / "out of range" / "must not be negative" errors: fixing range-validation failures across open-source libraries — this error's family across 42 libraries.

Related errors

• variableName is null
• caseInstanceId is null
• caseInstanceId is null
• variables is null
• variables is empty

AI-assisted analysis of flowable/flowable-engine@d6d39ce1c6 (2026-09-11). Data as JSON: /api/errors/d4a6b16c812df5a1. Report an issue: GitHub.