flowable/flowable-engine · error · ActivitiException

not found in process definition

Error message

${errorHandlerId} not found in process definition

What it means

After an error event handler (boundary/event-subprocess activity) is found by id, executeCatch looks it up in the process definition. If the referenced activity id does not exist in the deployed process definition, it throws ActivitiException.

Solutions

  1. Redeploy a consistent process definition and restart/complete affected process instances
  2. Verify the errorHandlerId corresponds to an existing activity id in the deployed BPMN XML
  3. Migrate or terminate old process instances that reference stale definitions
  4. Check deployment/definition cache consistency (same process definition version for execution)
Defensive patterns

Strategy: try-catch

Try / catch

try {
    completeTask(taskId);
} catch (org.activiti.engine.ActivitiException e) {
    if (e.getMessage() != null && e.getMessage().contains("not found in process definition")) {
        logger.error("Stale process definition for running execution", e);
    }
    throw e;
}

Prevention

When it happens

Trigger: An internal handler id (error event handler resolved by findLocalErrorEventHandler) is not present in the process definition returned for the current execution — typically an inconsistent or outdated process definition/execution pairing.

Common situations: Process definition redeployed/changed while old executions are running; custom code calling executeCatch paths with a hand-built id; corrupted or mismatched deployment data.

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

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

Appendix: source

Thrown at modules/flowable5-engine/src/main/java/org/activiti/engine/impl/bpmn/helper/ErrorPropagation.java:125

            }
        }
        return null;
    }

    private static ActivityExecution getSuperExecution(ActivityExecution execution) {
        ExecutionEntity executionEntity = (ExecutionEntity) execution;
        ExecutionEntity superExecution = executionEntity.getProcessInstance().getSuperExecution();
        if (superExecution != null && !superExecution.isScope()) {
            return superExecution.getParent();
        }
        return superExecution;
    }

    private static void executeCatch(String errorHandlerId, ActivityExecution execution, String errorCode) {
        ProcessDefinitionImpl processDefinition = ((ExecutionEntity) execution).getProcessDefinition();
        ActivityImpl errorHandler = processDefinition.findActivity(errorHandlerId);
        if (errorHandler == null) {
            throw new ActivitiException(errorHandlerId + " not found in process definition");
        }

        boolean matchingParentFound = false;
        ActivityExecution leavingExecution = execution;
        ActivityImpl currentActivity = (ActivityImpl) execution.getActivity();

        ScopeImpl catchingScope = errorHandler.getParent();
        if (catchingScope instanceof ActivityImpl) {
            ActivityImpl catchingScopeActivity = (ActivityImpl) catchingScope;
            if (!catchingScopeActivity.isScope()) { // event subprocesses
                catchingScope = catchingScopeActivity.getParent();
            }
        }

        if (catchingScope instanceof PvmProcessDefinition) {
            executeEventHandler(errorHandler, ((ExecutionEntity) execution).getProcessInstance(), errorCode);

        } else {

View on GitHub (pinned to d6d39ce1c6)