{"record":{"id":"7efd82d304d321bf","repo":"flowable/flowable-engine","slug":"variables-of-type-bytearray-cannot-be-used-to-quer","errorCode":null,"errorMessage":"Variables of type ByteArray cannot be used to query","messagePattern":"Variables of type ByteArray cannot be used to query","errorType":"validation","errorClass":"FlowableIllegalArgumentException","httpStatus":null,"severity":"error","filePath":"modules/flowable-variable-service/src/main/java/org/flowable/variable/service/impl/QueryVariableValue.java","lineNumber":60,"sourceCode":"    private String scopeType;\n\n    public QueryVariableValue(String name, Object value, QueryOperator operator, boolean local) {\n        this.name = name;\n        this.value = value;\n        this.operator = operator;\n        this.local = local;\n    }\n\n    public QueryVariableValue(String name, Object value, QueryOperator operator, boolean local, String scopeType) {\n        this(name, value, operator, local);\n        this.scopeType = scopeType;\n    }\n\n    public void initialize(VariableValueProvider valueProvider) {\n        if (valueField == null) {\n            valueType = valueProvider.findVariableType(value);\n            if (valueType instanceof ByteArrayType) {\n                throw new FlowableIllegalArgumentException(\"Variables of type ByteArray cannot be used to query\");\n            } else if (valueType instanceof JPAEntityVariableType && operator != QueryOperator.EQUALS) {\n                throw new FlowableIllegalArgumentException(\"JPA entity variables can only be used in 'variableValueEquals'\");\n            } else if (valueType instanceof JPAEntityListVariableType) {\n                throw new FlowableIllegalArgumentException(\"Variables containing a list of JPA entities cannot be used to query\");\n            } else {\n                // Type implementation determines which fields are set on the entity\n                valueField = valueProvider.createValueFields(name, valueType, value);\n            }\n        }\n    }\n\n    public void initialize(VariableServiceConfiguration variableServiceConfiguration) {\n        initialize(new VariableServiceConfigurationVariableValueProvider(variableServiceConfiguration));\n    }\n\n    public String getName() {\n        return name;\n    }","sourceCodeStart":42,"sourceCodeEnd":78,"githubUrl":"https://github.com/flowable/flowable-engine/blob/d6d39ce1c69ff244f2d9dc6af756a9b95e865586/modules/flowable-variable-service/src/main/java/org/flowable/variable/service/impl/QueryVariableValue.java#L42-L78","documentation":"QueryVariableValue.initialize(VariableValueProvider) resolves the variable type of the value used in a variable-value query predicate. If the resolved type is ByteArrayType, the value would be stored in a separate byte-array table that cannot be matched in a SQL query predicate, so Flowable throws FlowableIllegalArgumentException(\"Variables of type ByteArray cannot be used to query\").","triggerScenarios":"Calling taskService.createTaskQuery().variableValueEquals(\"var\", someByteArrayOrSerializableObject) (or any variableValue* operator) where the value resolves to ByteArrayType, e.g. a byte[], InputStream, or Serializable stored as bytes.","commonSituations":"Attempting to search variables that hold file contents or serialized objects; assuming all variable types are queryable; passing an object that Flowable persists as bytes because it is not one of the primitive queryable types.","solutions":["Query on a primitive/serializable value instead (String, Long, Double, Boolean, Date).","Store a searchable companion variable (e.g. a hash or name) alongside the byte-array variable and query that.","If you must find it, fetch candidate variables and filter byte-array content in application code."],"exampleFix":"// before\ntaskQuery.variableValueEquals(\"attachment\", fileBytes); // throws\n\n// after\ntaskQuery.variableValueEquals(\"attachmentName\", file.getName());","handlingStrategy":"type-guard","validationCode":"boolean queryable = !(value instanceof byte[])\n    && !(value instanceof InputStream)\n    && !(value instanceof Serializable && !(value instanceof String || value instanceof Number || value instanceof Boolean || value instanceof java.util.Date));","typeGuard":"static boolean isQueryableVariableValue(Object v) {\n    return v == null || v instanceof String || v instanceof Boolean\n        || v instanceof Integer || v instanceof Long || v instanceof Double\n        || v instanceof java.util.Date;\n}","tryCatchPattern":"try {\n    taskQuery.variableValueEquals(name, value);\n} catch (FlowableIllegalArgumentException e) {\n    // fall back to querying a shadow scalar variable\n    taskQuery.variableValueEquals(name + \"_key\", computeKey(value));\n}","preventionTips":["Only use String/Number/Boolean/Date values in variableValue* predicates.","Add a searchable companion variable when storing binary content.","Review variable types when moving from primitive to object/serialized variables."],"tags":["query","variables","unsupported-type"],"backgroundTag":"incompatible-source-type","analyzedSha":"d6d39ce1c69ff244f2d9dc6af756a9b95e865586","analyzedAt":"2026-09-11T06:41:19.413Z","contentChangedAt":"2026-09-11T06:41:19.413Z","schemaVersion":2},"datasetVersion":"2026-09-14T11:17:12.474Z"}