{"record":{"id":"809b60cbfe8ac328","repo":"flowable/flowable-engine","slug":"historyjobentity-failed","errorCode":null,"errorMessage":"${historyJobEntity} failed","messagePattern":"(.+?) failed","errorType":"exception","errorClass":"FlowableException","httpStatus":null,"severity":"error","filePath":"modules/flowable-job-service/src/main/java/org/flowable/job/service/impl/cmd/ExecuteHistoryJobCmd.java","lineNumber":63,"sourceCode":"    public Void execute(CommandContext commandContext) {\n        if (historyJobId == null) {\n            throw new FlowableIllegalArgumentException(\"historyJobId is null\");\n        }\n\n        HistoryJobEntity historyJobEntity = jobServiceConfiguration.getHistoryJobEntityManager().findById(historyJobId);\n        if (historyJobEntity == null) {\n            throw new JobNotFoundException(historyJobId);\n        }\n\n        if (LOGGER.isDebugEnabled()) {\n            LOGGER.debug(\"Executing historyJob {}\", historyJobEntity.getId());\n        }\n\n        try {\n            jobServiceConfiguration.getJobManager().execute(historyJobEntity);\n        } catch (Throwable exception) {\n            // Finally, Throw the exception to indicate the failure\n            throw new FlowableException(historyJobEntity + \" failed\", exception);\n        }\n\n        return null;\n    }\n\n}\n","sourceCodeStart":45,"sourceCodeEnd":70,"githubUrl":"https://github.com/flowable/flowable-engine/blob/d6d39ce1c69ff244f2d9dc6af756a9b95e865586/modules/flowable-job-service/src/main/java/org/flowable/job/service/impl/cmd/ExecuteHistoryJobCmd.java#L45-L70","documentation":"When the JobManager executes the history job and any Throwable escapes, ExecuteHistoryJobCmd wraps it in a FlowableException with the message \"<historyJobEntity> failed\" and the original as cause. It signals the history job handler itself threw — the real reason is always in the cause.","triggerScenarios":"HistoryJobEntity execution where the HistoryJobHandler throws: serialization/deserialization errors of job payload, missing entity types, database write failures in the history handler, or bugs in custom handlers.","commonSituations":"Async history enabled with a custom HistoryJobHandler that fails on new entity types; payload JSON corrupted or incompatible after a Flowable version upgrade; database constraints hit while persisting history.","solutions":["Inspect the cause exception of the FlowableException — it holds the actual handler failure.","Fix or patch the HistoryJobHandler registered for the failing entity type.","Check the history job payload in ACT_RU_HISTORY_JOB for corrupted/incompatible serialized data.","Verify custom handlers are updated after Flowable upgrades."],"exampleFix":"// before\ncatch (Throwable e) { log.error(e.getMessage()); } // only '<entity> failed'\n// after\ncatch (FlowableException e) {\n    log.error(\"History job failed\", e.getCause()); // real error\n}","handlingStrategy":"try-catch","validationCode":null,"typeGuard":null,"tryCatchPattern":"try { managementService.executeJob(jobId); } catch (FlowableException e) { Throwable root = e.getCause(); LOGGER.error(\"History/job execution failed\", root); }","preventionTips":["Always inspect the cause — the wrapper message only names the entity.","Keep custom HistoryJobHandlers covered by tests for all entity types.","Validate serialized history payload compatibility across versions."],"tags":["flowable","job-service","history-job","wrapped-exception"],"backgroundTag":"job-execution-failed","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"}