flowable/flowable-engine · error · FlowableException

Invalid usage of async_activate job handler, variable scope…

Error message

Invalid usage of async_activate job handler, variable scope is of type ${variableScope.getClass()}

What it means

AsyncActivatePlanItemInstanceJobHandler.execute() throws FlowException when the job handler is invoked with a variableScope (entity) whose type it does not recognize. The handler only knows how to process jobs whose scope is a PlanItemInstanceEntity; any other type means the job was created for a different handler or the data is corrupt. The message includes the offending class name for diagnosis.

Solutions

1. Verify the job's handler type matches its payload (job entity's handlerType should be async_activate only for plan-item activation jobs)
2. Delete the offending stale async job from ACT_RU_JOB / job tables so the engine skips it
3. Check for Flowable version mismatches between engines sharing the same database
4. Ensure no custom job handler registers the same TYPE ('async_activate') for different scopes

if (variableScope instanceof PlanItemInstanceEntity) {
    jobHandler.execute(job, variableScope, executionEntity, processInstanceId, commandContext);
} else {
    // wrong job/scope pairing — skip, log, or delete the stale job
}

boolean isAsyncActivateScope(Object variableScope) {
    return variableScope instanceof PlanItemInstanceEntity;
}

try {
    jobHandler.execute(job, variableScope, null, null, commandContext);
} catch (FlowableException e) {
    if (e.getMessage().contains("async_activate")) {
        // mismatched job scope — inspect/delete the job row or fix handler registration
    } else {
        throw e;
    }
}

When it happens

Trigger: A job of type 'async_activate' whose variableScope is not a PlanItemInstanceEntity — e.g. after deserializing a stale/mismatched job scope, or the job handler type string being reused for the wrong job category.

Common situations: Upgrading Flowable versions where job payload formats changed; manually inserting or migrating jobs between engines/databases; a custom job handler registered with a colliding TYPE constant.

Understand the failure class

Background: Type mismatch errors: IllegalArgumentException, TypeError and type guards across 150 open-source libraries — this error's family across 150 libraries.

Related errors

• Invalid usage of job handler, variable scope is of type
• Could not evaluate collection for repetition rule on plan…
• Delegate expression did not resolve to an implementation of
• Delegate expression did not resolve to an implementation of
• Delegate expression did not resolve to an implementation of

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

Appendix: source

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

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

    @Override
    public void execute(JobEntity job, String configuration, VariableScope variableScope, CommandContext commandContext) {
        if (variableScope instanceof PlanItemInstanceEntity planItemInstanceEntity) {
            CmmnEngineConfiguration cmmnEngineConfiguration = CommandContextUtil.getCmmnEngineConfiguration(commandContext);
            if (cmmnEngineConfiguration.isLoggingSessionEnabled()) {
                CmmnLoggingSessionUtil.addAsyncActivityLoggingData("Executing async job for " + planItemInstanceEntity.getPlanItemDefinitionId() + ", with job id " + job.getId(),
                        CmmnLoggingSessionConstants.TYPE_SERVICE_TASK_EXECUTE_ASYNC_JOB, job, planItemInstanceEntity.getPlanItemDefinition(), 
                        planItemInstanceEntity, cmmnEngineConfiguration.getObjectMapper());
            }
            
            CommandContextUtil.getAgenda(commandContext).planActivatePlanItemInstanceOperation(planItemInstanceEntity, configuration); // configuration == entryCriterionId
            
        } else {
            throw new FlowableException("Invalid usage of " + TYPE + " job handler, variable scope is of type " + variableScope.getClass());
        }
    }

}

View on GitHub (pinned to d6d39ce1c6)