{"record":{"id":"8010c0aa0cd75e49","repo":"flowable/flowable-engine","slug":"variablenames-are-null-or-empty-8010c0","errorCode":null,"errorMessage":"variableNames are null or empty","messagePattern":"variableNames are null or empty","errorType":"validation","errorClass":"FlowableIllegalArgumentException","httpStatus":null,"severity":"error","filePath":"modules/flowable-engine/src/main/java/org/flowable/engine/impl/ProcessInstanceQueryImpl.java","lineNumber":662,"sourceCode":"    public ProcessInstanceQuery suspended() {\n        if (inOrStatement) {\n            this.currentOrQueryObject.suspensionState = SuspensionState.SUSPENDED;\n        } else {\n            this.suspensionState = SuspensionState.SUSPENDED;\n        }\n        return this;\n    }\n\n    @Override\n    public ProcessInstanceQuery includeProcessVariables() {\n        this.includeProcessVariables = true;\n        return this;\n    }\n\n    @Override\n    public ProcessInstanceQuery includeProcessVariables(Collection<String> variableNames) {\n        if (variableNames == null || variableNames.isEmpty()) {\n            throw new FlowableIllegalArgumentException(\"variableNames are null or empty\");\n        }\n        includeProcessVariables();\n        this.variableNamesToInclude = new LinkedHashSet<>(variableNames);\n        return this;\n    }\n\n    @Override\n    public ProcessInstanceQuery withJobException() {\n        this.withJobException = true;\n        return this;\n    }\n\n    @Override\n    public ProcessInstanceQuery processInstanceName(String name) {\n        if (inOrStatement) {\n            this.currentOrQueryObject.name = name;\n        } else {\n            this.name = name;","sourceCodeStart":644,"sourceCodeEnd":680,"githubUrl":"https://github.com/flowable/flowable-engine/blob/d6d39ce1c69ff244f2d9dc6af756a9b95e865586/modules/flowable-engine/src/main/java/org/flowable/engine/impl/ProcessInstanceQueryImpl.java#L644-L680","documentation":"ProcessInstanceQueryImpl.includeProcessVariables(Collection<String>) narrows which process variables are included in query results. Flowable throws FlowableIllegalArgumentException when the collection is null or empty because including 'zero named variables' is meaningless — callers should either include all variables (no-arg includeProcessVariables()) or a specific non-empty list.","triggerScenarios":"Calling includeProcessVariables(null), includeProcessVariables(Collections.emptyList()), or passing a variable-name list that was emptied upstream (e.g., an empty user selection of 'columns to include').","commonSituations":"Dynamic report builders where the user deselected all variable columns; code that used to pass a full list and now receives an empty list after a refactor; confusion between the no-arg and collection-arg overloads of includeProcessVariables.","solutions":["Pass a non-empty collection of variable names, or call the no-arg includeProcessVariables() to include all variables","Guard the call: skip it entirely when the collection is empty","Verify where the variable-name list is built and why it ends up empty","Catch FlowableIllegalArgumentException and degrade to including all variables if acceptable"],"exampleFix":"// before\nquery.includeProcessVariables(variableNames); // may be empty\n// after\nif (variableNames != null && !variableNames.isEmpty()) {\n    query.includeProcessVariables(variableNames);\n} else {\n    query.includeProcessVariables(); // include all variables\n}","handlingStrategy":"validation","validationCode":"if (variableNames == null || variableNames.isEmpty()) {\n    // fall back to include-all instead of calling the collection overload\n}","typeGuard":"boolean hasVariableNames = variableNames != null && !variableNames.isEmpty();","tryCatchPattern":"try {\n    query.includeProcessVariables(variableNames);\n} catch (FlowableIllegalArgumentException e) {\n    query.includeProcessVariables();\n}","preventionTips":["Remember the no-arg includeProcessVariables() means 'all variables'","Validate dynamic column selections before query construction","Document that the collection overload requires a non-empty list"],"tags":["flowable","process-instance-query","empty-collection","variables"],"backgroundTag":"empty-required-field","analyzedSha":"d6d39ce1c69ff244f2d9dc6af756a9b95e865586","analyzedAt":"2026-09-11T06:41:19.413Z","contentChangedAt":"2026-09-11T06:41:19.413Z","schemaVersion":2},"datasetVersion":"2026-09-18T11:17:12.947Z"}