{"record":{"id":"853def2feaf1e2a8","repo":"flowable/flowable-engine","slug":"variable-853def","errorCode":null,"errorMessage":"variable '","messagePattern":"variable '","errorType":"exception","errorClass":"FlowableException","httpStatus":null,"severity":"error","filePath":"modules/flowable-variable-service/src/main/java/org/flowable/variable/service/impl/persistence/entity/VariableScopeImpl.java","lineNumber":794,"sourceCode":"                } else {\n                    variable = createVariableInstance(variableName, value);\n                }\n                usedVariablesCache.put(variableName, variable);\n\n            }\n\n        }\n        return null;\n    }\n\n    /**\n     * only called when a new variable is created on this variable scope. This method is also responsible for propagating the creation of this variable to the history.\n     */\n    protected void createVariableLocal(String variableName, Object value) {\n        ensureVariableInstancesInitialized();\n\n        if (variableInstances.containsKey(variableName)) {\n            throw new FlowableException(\"variable '\" + variableName + \"' already exists. Use setVariableLocal if you want to overwrite the value for \" + this);\n        }\n\n        createVariableInstance(variableName, value);\n    }\n\n    @Override\n    public void removeVariable(String variableName) {\n        ensureVariableInstancesInitialized();\n        if (variableInstances.containsKey(variableName)) {\n            removeVariableLocal(variableName);\n            return;\n        }\n        VariableScopeImpl parentVariableScope = getParentVariableScope();\n        if (parentVariableScope != null) {\n            parentVariableScope.removeVariable(variableName);\n        }\n    }\n","sourceCodeStart":776,"sourceCodeEnd":812,"githubUrl":"https://github.com/flowable/flowable-engine/blob/d6d39ce1c69ff244f2d9dc6af756a9b95e865586/modules/flowable-variable-service/src/main/java/org/flowable/variable/service/impl/persistence/entity/VariableScopeImpl.java#L776-L812","documentation":"createVariableLocal enforces that a newly created local variable does not already exist in this scope. If variableInstances already contains the given name, it throws FlowableException \"variable '<name>' already exists. Use setVariableLocal if you want to overwrite the value\".","triggerScenarios":"Calling createVariableLocal (directly or via internal APIs) for a variable name that already exists locally on the scope, e.g. re-creating a variable during delegate execution or in listener code instead of updating it.","commonSituations":"Custom delegates calling low-level create APIs; process re-execution after a retry where the variable already persisted; code that should use setVariable/setVariableLocal but calls create.","solutions":["Use setVariableLocal(name, value) (or setVariable) to create-or-overwrite instead of createVariableLocal","Check hasVariableLocal(name)/getVariableInstanceLocal(name) before creating","On retry/re-execution paths, upsert the variable rather than create it"],"exampleFix":"// before\nexecution.createVariableLocal(\"status\", \"new\");\n// after\nexecution.setVariableLocal(\"status\", \"new\");","handlingStrategy":"validation","validationCode":"if (scope.hasVariableLocal(variableName)) {\n    scope.setVariableLocal(variableName, value);\n} else {\n    scope.setVariableLocal(variableName, value); // set handles both create and overwrite\n}","typeGuard":null,"tryCatchPattern":"try {\n    execution.createVariableLocal(name, value);\n} catch (org.flowable.common.engine.api.FlowableException e) {\n    if (e.getMessage().startsWith(\"variable '\" + name + \"' already exists\")) {\n        execution.setVariableLocal(name, value);\n    } else {\n        throw e;\n    }\n}","preventionTips":["Prefer setVariableLocal/setVariable (create-or-overwrite) over low-level create APIs","Check hasVariableLocal before creating a variable","Make retry paths idempotent with upsert semantics"],"tags":["java","flowable","variables","duplicate"],"backgroundTag":"invalid-state-transition","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"}