flowable/flowable-engine · error · FlowableException

Could not find process definition needed for timer start eve

Error message

Could not find process definition needed for timer start event for job " + job

What it means

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.

Source

Thrown at modules/flowable-engine/src/main/java/org/flowable/engine/impl/jobexecutor/TimerStartEventJobHandler.java:50

public class TimerStartEventJobHandler extends TimerEventHandler implements JobHandler {

    private static final Logger LOGGER = LoggerFactory.getLogger(TimerStartEventJobHandler.class);

    public static final String TYPE = "timer-start-event";

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

    @Override
    public void execute(JobEntity job, String configuration, VariableScope variableScope, CommandContext commandContext) {

        ProcessDefinitionEntity processDefinitionEntity = ProcessDefinitionUtil
                .getProcessDefinitionFromDatabase(job.getProcessDefinitionId()); // From DB -> need to get latest suspended state
        if (processDefinitionEntity == null) {
            throw new FlowableException("Could not find process definition needed for timer start event for job " + job);
        }

        try {
            if (!processDefinitionEntity.isSuspended()) {
                ProcessEngineConfigurationImpl processEngineConfiguration = CommandContextUtil.getProcessEngineConfiguration(commandContext);
                FlowableEventDispatcher eventDispatcher = processEngineConfiguration.getEventDispatcher();
                if (eventDispatcher != null && eventDispatcher.isEnabled()) {
                    eventDispatcher.dispatchEvent(FlowableEventBuilder.createEntityEvent(FlowableEngineEventType.TIMER_FIRED, job),
                            processEngineConfiguration.getEngineCfgKey());
                }

                // Find initial flow element matching the signal start event
                org.flowable.bpmn.model.Process process = ProcessDefinitionUtil.getProcess(job.getProcessDefinitionId());
                String activityId = TimerEventHandler.getActivityIdFromConfiguration(configuration);
                if (activityId != null) {
                    FlowElement flowElement = process.getFlowElement(activityId, true);
                    if (flowElement == null) {
                        throw new FlowableException("Could not find matching FlowElement for activityId " + activityId + " in " + processDefinitionEntity);

View on GitHub (pinned to d6d39ce1c6)

Solutions

1. Delete the orphaned timer job from ACT_RU_JOB (or via JobService/management API)
2. Redeploy the process definition so the referenced processDefinitionId exists
3. Audit DB maintenance scripts that delete ACT_RE_PROCDEF rows without cleaning jobs

Example fix

// before
repositoryService.deleteDeployment(deploymentId); // jobs may linger if cascade skipped
// after
repositoryService.deleteDeployment(deploymentId, true); // cascades job cleanup

if (repositoryService.createProcessDefinitionQuery().processDefinitionId(job.getProcessDefinitionId()).count() == 0) { /* delete orphan job */ }

try { /* timer fires */ } catch (FlowableException e) { if (e.getMessage().startsWith("Could not find process definition")) { /* purge orphaned job */ } else throw e; }

When it happens

Trigger: 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).

Common situations: Deleting process definitions without removing their timer jobs, restoring databases partially, or stale jobs left after a failed undeploy.

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

• No process definition found for name:
• Process definition ${processDefinitionKey} was not found in
• No process definition found for key '{processDefinitionKey}'
• No process definition found for key '{processDefinitionKey}'
• Process definition with key '{processDefinitionKey}' and ten

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