{"record":{"id":"fea6280abf866ea2","repo":"flowable/flowable-engine","slug":"could-not-find-process-definition-needed-for-timer","errorCode":null,"errorMessage":"Could not find process definition needed for timer start event for job \" + job","messagePattern":"Could not find process definition needed for timer start event for job \" \\+ job","errorType":"exception","errorClass":"FlowableException","httpStatus":null,"severity":"error","filePath":"modules/flowable-engine/src/main/java/org/flowable/engine/impl/jobexecutor/TimerStartEventJobHandler.java","lineNumber":50,"sourceCode":"\npublic class TimerStartEventJobHandler extends TimerEventHandler implements JobHandler {\n\n    private static final Logger LOGGER = LoggerFactory.getLogger(TimerStartEventJobHandler.class);\n\n    public static final String TYPE = \"timer-start-event\";\n\n    @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\n        ProcessDefinitionEntity processDefinitionEntity = ProcessDefinitionUtil\n                .getProcessDefinitionFromDatabase(job.getProcessDefinitionId()); // From DB -> need to get latest suspended state\n        if (processDefinitionEntity == null) {\n            throw new FlowableException(\"Could not find process definition needed for timer start event for job \" + job);\n        }\n\n        try {\n            if (!processDefinitionEntity.isSuspended()) {\n                ProcessEngineConfigurationImpl processEngineConfiguration = CommandContextUtil.getProcessEngineConfiguration(commandContext);\n                FlowableEventDispatcher eventDispatcher = processEngineConfiguration.getEventDispatcher();\n                if (eventDispatcher != null && eventDispatcher.isEnabled()) {\n                    eventDispatcher.dispatchEvent(FlowableEventBuilder.createEntityEvent(FlowableEngineEventType.TIMER_FIRED, job),\n                            processEngineConfiguration.getEngineCfgKey());\n                }\n\n                // Find initial flow element matching the signal start event\n                org.flowable.bpmn.model.Process process = ProcessDefinitionUtil.getProcess(job.getProcessDefinitionId());\n                String activityId = TimerEventHandler.getActivityIdFromConfiguration(configuration);\n                if (activityId != null) {\n                    FlowElement flowElement = process.getFlowElement(activityId, true);\n                    if (flowElement == null) {\n                        throw new FlowableException(\"Could not find matching FlowElement for activityId \" + activityId + \" in \" + processDefinitionEntity);","sourceCodeStart":32,"sourceCodeEnd":68,"githubUrl":"https://github.com/flowable/flowable-engine/blob/d6d39ce1c69ff244f2d9dc6af756a9b95e865586/modules/flowable-engine/src/main/java/org/flowable/engine/impl/jobexecutor/TimerStartEventJobHandler.java#L32-L68","documentation":"Thrown by TimerStartEventJobHandler.execute when the process definition referenced by the timer start event job no longer exists in the database. The handler must load the definition (with suspended state) to fire the timer start event, so a missing row is fatal.","triggerScenarios":"A timer start event job fires after its process definition was deleted from ACT_RE_PROCDEF (e.g. cascade delete, DB cleanup, or definition removed while jobs remained).","commonSituations":"Deleting process definitions without removing their timer jobs, restoring databases partially, or stale jobs left after a failed undeploy.","solutions":["Delete the orphaned timer job from ACT_RU_JOB (or via JobService/management API)","Redeploy the process definition so the referenced processDefinitionId exists","Audit DB maintenance scripts that delete ACT_RE_PROCDEF rows without cleaning jobs"],"exampleFix":"// before\nrepositoryService.deleteDeployment(deploymentId); // jobs may linger if cascade skipped\n// after\nrepositoryService.deleteDeployment(deploymentId, true); // cascades job cleanup","handlingStrategy":"validation","validationCode":"if (repositoryService.createProcessDefinitionQuery().processDefinitionId(job.getProcessDefinitionId()).count() == 0) { /* delete orphan job */ }","typeGuard":null,"tryCatchPattern":"try { /* timer fires */ } catch (FlowableException e) { if (e.getMessage().startsWith(\"Could not find process definition\")) { /* purge orphaned job */ } else throw e; }","preventionTips":["Always delete deployments with cascade so jobs are cleaned","Reconcile timer jobs against process definitions after DB maintenance"],"tags":["flowable","timer","process-definition","not-found"],"backgroundTag":"entity-not-found","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"}