flowable/flowable-engine · error · FlowableException

Invalid usage of ${TYPE} job handler, case instance ${caseIn

Error message

Invalid usage of ${TYPE} job handler, case instance ${caseInstanceId} was not found.

What it means

Flowable's async initialize-plan-model job handler runs when a delayed async case start job fires. It looks up the case instance by id and, if it no longer exists, cannot proceed to plan the init plan model operation, so it throws FlowableException. This indicates the async job is orphaned — its target case instance was deleted (e.g. via history cleanup, manual delete, or a rolled-back transaction) before the job executed.

Source

Thrown at modules/flowable-cmmn-engine/src/main/java/org/flowable/cmmn/engine/impl/job/AsyncInitializePlanModelJobHandler.java:41

/**
 * @author martin.grofcik
 */
public class AsyncInitializePlanModelJobHandler implements JobHandler {
    
    public static final String TYPE = "cmmn-async-init-plan-model-instance";

    @Override
    public String getType() {
        return TYPE;
    }

    @Override
    public void execute(JobEntity job, String caseInstanceId, VariableScope variableScope, CommandContext commandContext) {
        CaseInstanceEntity caseInstance = CommandContextUtil.getCaseInstanceEntityManager(commandContext).findById(caseInstanceId);
        if (caseInstance != null) {
            CommandContextUtil.getAgenda(commandContext).planInitPlanModelOperation(caseInstance);
        } else {
            throw new FlowableException("Invalid usage of " + TYPE + " job handler, case instance " + caseInstanceId + " was not found.");
        }
    }

}

View on GitHub (pinned to d6d39ce1c6)

Solutions

1. Check whether the case instance actually still exists (ACT_CMMN_HI_CASEINST / case instance tables) for the id in the message; if it was intentionally deleted, delete the corresponding async job row so the executor stops retrying.
2. Investigate what removed the case instance (history cleanup config, manual deletes) and align job retention with case instance retention.
3. If this follows a failed case initialization transaction, verify the CMMN engine creates the case instance before scheduling the async init job and that no rollback leaves the job behind.
4. Reproduce the case start locally; if the case instance is missing because creation failed, fix the underlying creation error rather than the symptom.

Example fix

// before: orphaned job retried forever, throwing
// after: purge orphaned async jobs for missing case instances before execution
CaseInstanceEntity caseInstance = commandContext.getCaseInstanceEntityManager().findById(caseInstanceId);
if (caseInstance == null) {
    commandContext.getJobManager().deleteJob(job);
    return; // or log a warning instead of throwing
}

CaseInstance ci = cmmnRuntimeService.createCaseInstanceQuery().caseInstanceId(id).singleResult();
if (ci == null) throw new IllegalStateException("Case instance " + id + " gone before async init job ran");

boolean caseInstanceExists(String id) {
    return cmmnRuntimeService.createCaseInstanceQuery().caseInstanceId(id).count() > 0;
}

try {
    // start case / wait for async init
} catch (FlowableException e) {
    if (e.getMessage() != null && e.getMessage().contains("was not found")) {
        log.warn("Orphaned async init job for missing case instance; purging job");
        jobService.deleteJob(jobId);
    } else { throw e; }
}

When it happens

Trigger: An async job of TYPE 'async-init-plan-model' is executed by the async executor but CommandContextUtil.getCaseInstanceEntityManager(...).findById(caseInstanceId) returns null, typically because the case instance row was removed between job creation and job execution.

Common situations: History/job cleanup jobs deleting case instance rows while async jobs remain; manual deletion of case instance data via SQL or API; running the async executor against a shared job table where another node already started and rolled back the case; restoring a database backup with jobs but without instance rows.

Understand the failure class

Background: "Not found" and "does not exist" errors: why "Task not found", "No such folder", and "Can't find" fire when a lookup comes back empty — this error's family across 14 libraries.

Related errors

• Case instance id is null
• Cannot find case instance for id ${caseInstanceId}
• Cannot find case instance with id
• Cannot find case instance with id
• caseInstanceId is null

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