flowable/flowable-engine · error · ActivitiIllegalArgumentException

Variables of type ByteArray cannot be used to query

Error message

Variables of type ByteArray cannot be used to query

What it means

When a query variable value is initialized, the engine resolves its VariableType; ByteArrayType variables are stored as opaque binary blobs and cannot be compared in SQL, so querying on them is rejected with ActivitiIllegalArgumentException. Only query variables with types that map to queryable columns are allowed.

Source

Thrown at modules/flowable5-engine/src/main/java/org/activiti/engine/impl/QueryVariableValue.java:51

    private String name;
    private Object value;
    private QueryOperator operator;

    private VariableInstanceEntity variableInstanceEntity;
    private boolean local;

    public QueryVariableValue(String name, Object value, QueryOperator operator, boolean local) {
        this.name = name;
        this.value = value;
        this.operator = operator;
        this.local = local;
    }

    public void initialize(VariableTypes types) {
        if (variableInstanceEntity == null) {
            VariableType type = types.findVariableType(value);
            if (type instanceof ByteArrayType) {
                throw new ActivitiIllegalArgumentException("Variables of type ByteArray cannot be used to query");
            } else if (type instanceof JPAEntityVariableType && operator != QueryOperator.EQUALS) {
                throw new ActivitiIllegalArgumentException("JPA entity variables can only be used in 'variableValueEquals'");
            } else if (type instanceof JPAEntityListVariableType) {
                throw new ActivitiIllegalArgumentException("Variables containing a list of JPA entities cannot be used to query");
            } else {
                // Type implementation determines which fields are set on the entity
                variableInstanceEntity = VariableInstanceEntity.create(name, type, value);
            }
        }
    }

    public String getName() {
        return name;
    }

    public String getOperator() {
        if (operator != null) {
            return operator.toString();

View on GitHub (pinned to d6d39ce1c6)

Solutions

1. Do not query on byte[] variables; query on a companion metadata variable instead (e.g. filename, mimeType, checksum stored as String).
2. Refactor large content into content stored elsewhere (file store) and keep only an id/reference in the process variable.
3. Change the variable to a queryable type (String, Long, Serializable handled by the engine's type registry) if comparison is truly needed.
4. Catch ActivitiIllegalArgumentException to give users a clear 'this variable type is not searchable' message.

Example fix

// before
runtimeService.createProcessInstanceQuery()
    .variableValueEquals("attachment", fileBytes)
    .singleResult();

// after
runtimeService.createProcessInstanceQuery()
    .variableValueEquals("attachmentChecksum", checksum)
    .singleResult();

if (value instanceof byte[]) {
    throw new IllegalArgumentException("byte[] variables cannot be used in variable queries; query a metadata variable instead");
}
query.variableValueEquals(name, value);

boolean isQueryableVariableValue(Object value) {
    return !(value instanceof byte[]);
}

try {
    query.variableValueEquals(name, value);
} catch (org.activiti.engine.ActivitiIllegalArgumentException e) {
    // fall back to a metadata/companion variable query
}

When it happens

Trigger: Calling variableValueEquals/variableValueGreaterThan etc. (on ProcessInstanceQuery, TaskQuery, HistoricProcessInstanceQuery) with a value whose resolved type is ByteArrayType, e.g. a byte[] value.

Common situations: Querying process/task variables where a previous setVariable stored serialized content (documents, images, serialized objects) as byte[]; attempting to find executions by content of an uploaded file; confusion between variableValueEquals semantics and blob storage.

Understand the failure class

Background: UnsupportedOperationException and "is not supported" errors: when a library deliberately refuses a call — this error's family across 30 libraries.

Related errors

• Variables of type ByteArray cannot be used to query
• JPA entity variables can only be used in 'variableValueEqual
• Variables containing a list of JPA entities cannot be used t
• Only string variable values are supported using like, but wa
• Unsupported variable query operation:

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