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.

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)

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 ${TYPE} job handler, variable scope is of t
• Delegate expression ${expression} did not resolve to an impl
• Delegate expression ${expression} did not resolve to an impl
• Delegate expression ${expression} did not resolve to an impl
• Could not evaluate collection for repetition rule on plan it

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