{"record":{"id":"648178e31f27613c","repo":"flowable/flowable-engine","slug":"cannot-set-jpa-variable-session-not-configured","errorCode":null,"errorMessage":"Cannot set JPA variable: ${session} not configured","messagePattern":"Cannot set JPA variable: (.+?) not configured","errorType":"exception","errorClass":"FlowableException","httpStatus":null,"severity":"error","filePath":"modules/flowable-variable-service/src/main/java/org/flowable/variable/service/impl/types/JPAEntityVariableType.java","lineNumber":60,"sourceCode":"\n    @Override\n    public boolean isCachable() {\n        return forceCacheable;\n    }\n\n    @Override\n    public boolean isAbleToStore(Object value) {\n        if (value == null) {\n            return true;\n        }\n        return mappings.isJPAEntity(value);\n    }\n\n    @Override\n    public void setValue(Object value, ValueFields valueFields) {\n        EntityManagerSession entityManagerSession = Context.getCommandContext().getSession(EntityManagerSession.class);\n        if (entityManagerSession == null) {\n            throw new FlowableException(\"Cannot set JPA variable: \" + EntityManagerSession.class + \" not configured\");\n        } else {\n            // Before we set the value we must flush all pending changes from\n            // the entitymanager\n            // If we don't do this, in some cases the primary key will not yet\n            // be set in the object\n            // which will cause exceptions down the road.\n            entityManagerSession.flush();\n        }\n\n        if (value != null) {\n            String className = mappings.getJPAClassString(value);\n            String idString = mappings.getJPAIdString(value);\n            valueFields.setTextValue(className);\n            valueFields.setTextValue2(idString);\n        } else {\n            valueFields.setTextValue(null);\n            valueFields.setTextValue2(null);\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/types/JPAEntityVariableType.java#L42-L78","documentation":"JPAEntityVariableType.setValue needs the EntityManagerSession from the current CommandContext to flush pending changes and resolve the entity's id. If no EntityManagerSession is registered (JPA not configured for this engine), it throws before touching the entity.","triggerScenarios":"Calling setValue (e.g. runtimeService.setVariable / taskService.setVariable with a JPA entity value) while the process engine was built without jpaPersistenceUnitName/jpaEntityManagerFactory configuration.","commonSituations":"Forgetting jpa-persistence-unit / jpaEntityManagerFactory in the engine config after adding JPA variable usage; unit tests using the default in-memory engine config without JPA; multiple engines where the wrong (non-JPA) engine executes the variable write.","solutions":["Configure the engine with JPA: set jpaPersistenceUnitName (or jpaEntityManagerFactory) on SpringProcessEngineConfiguration / ProcessEngineConfiguration so an EntityManagerSession is registered.","Verify the variable is set on the same engine instance that has JPA configured, not a second default engine.","In tests, add the JPA configuration to the test engine builder or mock/stub the EntityManagerSession.","If JPA variables were never intended, pass the entity's id (String/Long) instead of the entity object itself."],"exampleFix":"// before\nProcessEngineConfiguration.createStandaloneProcessEngineConfiguration()...buildProcessEngine();\n// after\nSpringProcessEngineConfiguration cfg = new SpringProcessEngineConfiguration();\ncfg.setJpaPersistenceUnitName(\"myUnit\"); // registers EntityManagerSession","handlingStrategy":"validation","validationCode":"EntityManagerSession s = Context.getCommandContext().getSession(EntityManagerSession.class); // inside command, or simply check engine config\nif (processEngineConfiguration.getJpaEntityManagerFactory() == null && processEngineConfiguration.getJpaPersistenceUnitName() == null) throw new IllegalStateException(\"JPA not configured for this engine\");","typeGuard":"boolean jpaEnabled(ProcessEngineConfiguration cfg) { return cfg.getJpaEntityManagerFactory() != null || cfg.getJpaPersistenceUnitName() != null; }","tryCatchPattern":"try { runtimeService.setVariable(executionId, \"entity\", jpaEntity); } catch (FlowableException e) { if (e.getMessage().contains(\"EntityManagerSession\") && e.getMessage().contains(\"not configured\")) { throw new IllegalStateException(\"Enable JPA on the process engine configuration\", e); } throw e; }","preventionTips":["Set jpaPersistenceUnitName or jpaEntityManagerFactory on the engine configuration before using JPA variables.","Ensure only one, correctly configured engine instance is used in tests and application code.","Centralize engine configuration so JPA settings cannot be omitted by accident."],"tags":["jpa","engine-configuration","entitymanager","missing-config"],"backgroundTag":"missing-required-config","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"}