flowable/flowable-engine · error · FlowableException

Could not find matching FlowElement for activityId " + activ

Error message

Could not find matching FlowElement for activityId " + activityId + " in " + processDefinitionEntity

What it means

Thrown by TimerStartEventJobHandler.execute when the activityId encoded in the timer job's configuration does not resolve to a FlowElement in the process model. Used for signal/multiple start events, the handler locates the specific initial flow element to start the instance with.

Source

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

            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);
                    }
                    ProcessInstanceHelper processInstanceHelper = processEngineConfiguration.getProcessInstanceHelper();
                    processInstanceHelper.createAndStartProcessInstanceWithInitialFlowElement(processDefinitionEntity, null, null, null, flowElement, process
                            , null, null, null, null, true);
                } else {
                    new StartProcessInstanceCmd(processDefinitionEntity.getKey(), null, null, null, job.getTenantId()).execute(commandContext);
                }

            } else {
                LOGGER.debug("ignoring timer of suspended process definition {}", processDefinitionEntity.getId());
            }
        } catch (RuntimeException e) {
            LOGGER.error("exception during timer execution for {}", job, e);
            throw e;
        } catch (Exception e) {
            LOGGER.error("exception during timer execution for {}", job, e);
            throw new FlowableException("exception during timer execution for " + job, e);
        }

View on GitHub (pinned to d6d39ce1c6)

Solutions

  1. Ensure the activityId in the job configuration matches a flow element id in the deployed model
  2. Redeploy the process definition / recreate the timer job so configuration and model agree
  3. Remove stale timer jobs from ACT_RU_JOB after model changes
Defensive patterns

Strategy: validation

Validate before calling

// verify configured activityId exists before firing: process.getFlowElement(activityId, true) != null

Try / catch

try { /* timer fires */ } catch (FlowableException e) { if (e.getMessage().startsWith("Could not find matching FlowElement")) { /* recreate job / redeploy model */ } else throw e; }

Prevention

When it happens

Trigger: A timer start job with configuration containing an activityId absent from the parsed process (e.g. model redeployed/changed so the element was removed or renamed while the old job remained).

Common situations: Redeploying a changed BPMN while old timer jobs persisted, hand-editing job configuration, or version-skew between the job's process definition and the resolved model.

Understand the failure class

Background: 'Could not be found', 'does not exist', 'not found in database': the resource-not-found family when an ID, slug, key, or URI lookup comes back empty — this error's family across 20 libraries.

Related errors

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