{"record":{"id":"19cf9f8db9837f65","repo":"flowable/flowable-engine","slug":"invalid-usage-of-async-activate-job-handler-varia","errorCode":null,"errorMessage":"Invalid usage of async_activate job handler, variable scope is of type ${variableScope.getClass()}","messagePattern":"Invalid usage of async_activate job handler, variable scope is of type (.+?)","errorType":"exception","errorClass":"FlowableException","httpStatus":null,"severity":"error","filePath":"modules/flowable-cmmn-engine/src/main/java/org/flowable/cmmn/engine/impl/job/AsyncActivatePlanItemInstanceJobHandler.java","lineNumber":51,"sourceCode":"    @Override\n    public String getType() {\n        return TYPE;\n    }\n\n    @Override\n    public void execute(JobEntity job, String configuration, VariableScope variableScope, CommandContext commandContext) {\n        if (variableScope instanceof PlanItemInstanceEntity planItemInstanceEntity) {\n            CmmnEngineConfiguration cmmnEngineConfiguration = CommandContextUtil.getCmmnEngineConfiguration(commandContext);\n            if (cmmnEngineConfiguration.isLoggingSessionEnabled()) {\n                CmmnLoggingSessionUtil.addAsyncActivityLoggingData(\"Executing async job for \" + planItemInstanceEntity.getPlanItemDefinitionId() + \", with job id \" + job.getId(),\n                        CmmnLoggingSessionConstants.TYPE_SERVICE_TASK_EXECUTE_ASYNC_JOB, job, planItemInstanceEntity.getPlanItemDefinition(), \n                        planItemInstanceEntity, cmmnEngineConfiguration.getObjectMapper());\n            }\n            \n            CommandContextUtil.getAgenda(commandContext).planActivatePlanItemInstanceOperation(planItemInstanceEntity, configuration); // configuration == entryCriterionId\n            \n        } else {\n            throw new FlowableException(\"Invalid usage of \" + TYPE + \" job handler, variable scope is of type \" + variableScope.getClass());\n        }\n    }\n\n}\n","sourceCodeStart":33,"sourceCodeEnd":56,"githubUrl":"https://github.com/flowable/flowable-engine/blob/d6d39ce1c69ff244f2d9dc6af756a9b95e865586/modules/flowable-cmmn-engine/src/main/java/org/flowable/cmmn/engine/impl/job/AsyncActivatePlanItemInstanceJobHandler.java#L33-L56","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Verify the job's handler type matches its payload (job entity's handlerType should be async_activate only for plan-item activation jobs)","Delete the offending stale async job from ACT_RU_JOB / job tables so the engine skips it","Check for Flowable version mismatches between engines sharing the same database","Ensure no custom job handler registers the same TYPE ('async_activate') for different scopes"],"exampleFix":null,"handlingStrategy":"try-catch","validationCode":"if (variableScope instanceof PlanItemInstanceEntity) {\n    jobHandler.execute(job, variableScope, executionEntity, processInstanceId, commandContext);\n} else {\n    // wrong job/scope pairing — skip, log, or delete the stale job\n}","typeGuard":"boolean isAsyncActivateScope(Object variableScope) {\n    return variableScope instanceof PlanItemInstanceEntity;\n}","tryCatchPattern":"try {\n    jobHandler.execute(job, variableScope, null, null, commandContext);\n} catch (FlowableException e) {\n    if (e.getMessage().contains(\"async_activate\")) {\n        // mismatched job scope — inspect/delete the job row or fix handler registration\n    } else {\n        throw e;\n    }\n}","preventionTips":["Keep Flowable versions identical across engines sharing a database","Register custom job handlers with unique TYPE constants that do not collide with async_activate","Audit job tables for stale or hand-inserted jobs after migrations"],"tags":["flowable","cmmn","job-handler","async","type-mismatch"],"backgroundTag":"type-mismatch","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"}