What causes "${historyJobEntity} failed" in flowable/flowable-engine?

Inspect the cause exception of the FlowableException — it holds the actual handler failure.

flowable/flowable-engine · error · FlowableException

${historyJobEntity} failed

Error message

${historyJobEntity} failed

What it means

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.

Source

Thrown at modules/flowable-job-service/src/main/java/org/flowable/job/service/impl/cmd/ExecuteHistoryJobCmd.java:63

    public Void execute(CommandContext commandContext) {
        if (historyJobId == null) {
            throw new FlowableIllegalArgumentException("historyJobId is null");
        }

        HistoryJobEntity historyJobEntity = jobServiceConfiguration.getHistoryJobEntityManager().findById(historyJobId);
        if (historyJobEntity == null) {
            throw new JobNotFoundException(historyJobId);
        }

        if (LOGGER.isDebugEnabled()) {
            LOGGER.debug("Executing historyJob {}", historyJobEntity.getId());
        }

        try {
            jobServiceConfiguration.getJobManager().execute(historyJobEntity);
        } catch (Throwable exception) {
            // Finally, Throw the exception to indicate the failure
            throw new FlowableException(historyJobEntity + " failed", exception);
        }

        return null;
    }

}

View on GitHub (pinned to d6d39ce1c6)

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.

Example fix

// before
catch (Throwable e) { log.error(e.getMessage()); } // only '<entity> failed'
// after
catch (FlowableException e) {
    log.error("History job failed", e.getCause()); // real error
}

Defensive patterns

Strategy: try-catch

Try / catch

try { managementService.executeJob(jobId); } catch (FlowableException e) { Throwable root = e.getCause(); LOGGER.error("History/job execution failed", root); }

Prevention

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.

When it happens

Trigger: 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.

Common situations: 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.

Related errors

AI-assisted analysis of flowable/flowable-engine@d6d39ce1c6 (2026-09-11). Data as JSON: /api/errors/809b60cbfe8ac328. Report an issue: GitHub.