{"record":{"id":"7130778ff4ed82b7","repo":"flowable/flowable-engine","slug":"variable-variablename-already-exists-us","errorCode":null,"errorMessage":"variable '\" + variableName + \"' already exists. Use setVariableLocal if you want to overwrite the value for \" + this","messagePattern":"variable '\" \\+ variableName \\+ \"' already exists\\. Use setVariableLocal if you want to overwrite the value for \" \\+ this","errorType":"exception","errorClass":"FlowableException","httpStatus":null,"severity":"error","filePath":"modules/flowable-engine/src/main/java/org/flowable/engine/impl/persistence/entity/ExecutionEntityImpl.java","lineNumber":894,"sourceCode":"        variableListenerSession.addVariableData(variableInstance.getName(), VariableListenerSessionData.VARIABLE_CREATE, \n                variableInstance.getProcessInstanceId(), ScopeTypes.BPMN, variableInstance.getProcessDefinitionId());\n        \n        Clock clock = CommandContextUtil.getProcessEngineConfiguration().getClock();\n        // Record historic variable\n        CommandContextUtil.getHistoryManager().recordVariableCreate(variableInstance, clock.getCurrentTime());\n\n        // Record historic detail\n        CommandContextUtil.getHistoryManager().recordHistoricDetailVariableCreate(variableInstance, sourceExecution, true,\n            getRelatedActivityInstanceId(sourceExecution), clock.getCurrentTime());\n\n        return variableInstance;\n    }\n    \n    protected void createVariableLocal(String variableName, Object value, ExecutionEntity sourceActivityExecution) {\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, sourceActivityExecution);\n    }\n    \n    @Override\n    protected void updateVariableInstance(VariableInstanceEntity variableInstance, Object value) {\n        updateVariableInstance(variableInstance, value, this);\n    }\n\n    protected void updateVariableInstance(VariableInstanceEntity variableInstance, Object value, ExecutionEntity sourceExecution) {\n        super.updateVariableInstance(variableInstance, value);\n\n        ProcessEngineConfigurationImpl processEngineConfiguration = CommandContextUtil.getProcessEngineConfiguration();\n        VariableListenerSession variableListenerSession = Context.getCommandContext().getSession(VariableListenerSession.class);\n        variableListenerSession.addVariableData(variableInstance.getName(), VariableListenerSessionData.VARIABLE_UPDATE, \n                variableInstance.getProcessInstanceId(), ScopeTypes.BPMN, variableInstance.getProcessDefinitionId());\n        ","sourceCodeStart":876,"sourceCodeEnd":912,"githubUrl":"https://github.com/flowable/flowable-engine/blob/d6d39ce1c69ff244f2d9dc6af756a9b95e865586/modules/flowable-engine/src/main/java/org/flowable/engine/impl/persistence/entity/ExecutionEntityImpl.java#L876-L912","documentation":"ExecutionEntityImpl.createVariableLocal refuses to overwrite an existing variable when creating a local variable: if variableInstances already contains the name it throws this FlowableException, directing the caller to setVariableLocal for overwriting. It guards against silently replacing variable values.","triggerScenarios":"Calling createVariableLocal (directly or via APIs that create local variables, e.g. executionEntity.createVariableLocal(name, value), DelegateExecution variable creation in JavaDelegates/ExecutionListeners) with a variable name that already exists locally on that execution.","commonSituations":"Delegate/listener code that initializes a local variable on re-entry or retry (looped subprocess, boundary-event re-execution) where the variable was set in a previous pass; parallel branches each attempting to create the same local name; double-invocation of initialization code.","solutions":["Use setVariableLocal(variableName, value) instead of createVariableLocal when overwriting an existing value is intended.","Guard with a containsKey/hasVariableLocal check and only create when absent, otherwise update.","Uniquify the variable name per activity instance/loop iteration so re-entry doesn't collide."],"exampleFix":"// before\nexecution.createVariableLocal(\"retryCount\", 0); // throws on retry pass\n// after\nif (!execution.hasVariableLocal(\"retryCount\")) {\n    execution.createVariableLocal(\"retryCount\", 0);\n} else {\n    execution.setVariableLocal(\"retryCount\", 0);\n}","handlingStrategy":"validation","validationCode":"// Java: check existence before creating local variable\nif (execution.hasVariableLocal(variableName)) {\n    execution.setVariableLocal(variableName, value);\n} else {\n    execution.createVariableLocal(variableName, value);\n}","typeGuard":"boolean canCreateLocal(VariableScope scope, String name) {\n    return !scope.hasVariableLocal(name);\n}","tryCatchPattern":"try {\n    execution.createVariableLocal(name, value);\n} catch (FlowableException e) {\n    if (e.getMessage().contains(\"already exists\")) {\n        execution.setVariableLocal(name, value);\n    } else { throw e; }\n}","preventionTips":["Default to setVariableLocal unless you specifically need create-once semantics.","Make delegates/listeners idempotent for retries and loop iterations.","Uniquify variable names per activity/loop when multiple branches write.","Check hasVariableLocal before any create call."],"tags":["variables","flowable","duplicate","state"],"backgroundTag":"file-already-exists","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"}