{"record":{"id":"4e04b12ff7065d2a","repo":"flowable/flowable-engine","slug":"entity-does-not-exist-entityclass-primaryk","errorCode":null,"errorMessage":"Entity does not exist: ${entityClass} - ${primaryKey}","messagePattern":"Entity does not exist: (.+?) - (.+?)","errorType":"exception","errorClass":"FlowableException","httpStatus":null,"severity":"error","filePath":"modules/flowable-variable-service/src/main/java/org/flowable/variable/service/impl/types/JPAEntityMappings.java","lineNumber":125,"sourceCode":"    }\n\n    public Object getJPAEntity(String className, String idString) {\n        Class<?> entityClass = null;\n        entityClass = ReflectUtil.loadClass(className);\n\n        EntityMetaData metaData = getEntityMetaData(entityClass);\n\n        // Create primary key of right type\n        Object primaryKey = createId(metaData, idString);\n        return findEntity(entityClass, primaryKey);\n    }\n\n    private Object findEntity(Class<?> entityClass, Object primaryKey) {\n        EntityManager em = Context.getCommandContext().getSession(EntityManagerSession.class).getEntityManager();\n\n        Object entity = em.find(entityClass, primaryKey);\n        if (entity == null) {\n            throw new FlowableException(\"Entity does not exist: \" + entityClass.getName() + \" - \" + primaryKey);\n        }\n        return entity;\n    }\n\n    public Object createId(EntityMetaData metaData, String string) {\n        Class<?> type = metaData.getIdType();\n        // According to JPA-spec all primitive types (and wrappers) are\n        // supported, String, util.Date, sql.Date,\n        // BigDecimal and BigInteger\n        if (type == Long.class || type == long.class) {\n            return Long.parseLong(string);\n        } else if (type == String.class) {\n            return string;\n        } else if (type == Byte.class || type == byte.class) {\n            return Byte.parseByte(string);\n        } else if (type == Short.class || type == short.class) {\n            return Short.parseShort(string);\n        } else if (type == Integer.class || type == int.class) {","sourceCodeStart":107,"sourceCodeEnd":143,"githubUrl":"https://github.com/flowable/flowable-engine/blob/d6d39ce1c69ff244f2d9dc6af756a9b95e865586/modules/flowable-variable-service/src/main/java/org/flowable/variable/service/impl/types/JPAEntityMappings.java#L107-L143","documentation":"When deserializing a JPA entity variable from storage, Flowable loads the entity via EntityManager.find(entityClass, primaryKey). If the find returns null — no row exists for that primary key — Flowable throws this FlowableException naming the entity class and key.","triggerScenarios":"findEntity() called from getJPAEntity(className, idString): the stored variable references an entity whose row was deleted from the database, or the primary key string was converted to a value that no longer matches any row (wrong createId type, e.g. Long vs String mismatch).","commonSituations":"Referential integrity without FK constraints: process variables outlive the entity rows; data purged by cleanup jobs or cascading deletes while the process instance still holds a JPA variable; running against a different database/environment than the one the variable was created in; id type conversion (createId) producing a differently-typed key that finds nothing.","solutions":["Restore the missing row or correct the database the engine is pointed at (verify persistence unit/DataSource matches the data that created the variable).","Check the id string-to-type conversion in createId(): the parsed key (e.g. Long.parseLong) must match the @Id column type and value.","Delete or fix stale variables referencing removed entities; add cleanup of process instances when their referenced entities are deleted.","Guard application code: catch FlowableException around variable retrieval (getVariable of a JPA type) and handle a missing entity explicitly."],"exampleFix":"// before\nOrder order = (Order) taskService.getVariable(taskId, \"order\"); // throws if row deleted\n// after\nObject v = taskService.getVariable(taskId, \"order\");\nOrder order = (v instanceof Order) ? (Order) v : orderRepository.findFallback(taskId);","handlingStrategy":"try-catch","validationCode":"// verify the referenced entity exists before relying on the variable\nObject key = taskService.getVariable(taskId, \"orderId\");\nboolean exists = key != null && entityManager.find(Order.class, key) != null;","typeGuard":"boolean entityExists(EntityManager em, Class<?> type, Object pk) {\n    return pk != null && em.find(type, pk) != null;\n}","tryCatchPattern":"try {\n    Object v = runtimeService.getVariable(executionId, \"jpaVar\");\n} catch (org.flowable.common.engine.api.FlowableException e) {\n    if (e.getMessage().startsWith(\"Entity does not exist\")) {\n        // handle deleted entity: re-create, reassign variable, or complete/terminate the process\n    }\n}","preventionTips":["Never hard-delete entity rows referenced by in-flight process variables; use soft deletes.","Enable FK constraints or periodic consistency checks between variables and entity tables.","Ensure id type used in createId matches the @Id column type exactly.","Point the engine at the same database/environment where the variables were created."],"tags":["jpa","entity-not-found","database","variables"],"backgroundTag":"entity-not-found","analyzedSha":"d6d39ce1c69ff244f2d9dc6af756a9b95e865586","analyzedAt":"2026-09-11T06:41:19.413Z","contentChangedAt":"2026-09-11T06:41:19.413Z","schemaVersion":2},"datasetVersion":"2026-09-14T05:17:10.506Z"}