What causes "No process definition found for key '{processDefinitionKey}'" in flowable/flowable-engine?

Deploy a BPMN process definition whose process id equals the requested key before calling the API

flowable/flowable-engine · error · FlowableObjectNotFoundException

No process definition found for key '{processDefinitionKey}'

Error message

No process definition found for key '{processDefinitionKey}'

What it means

Flowable throws this FlowableObjectNotFoundException when no process definition is deployed with the given process definition key (and no tenant filtering applies). The lookup in getLatestProcessDefinitionByKey queried the process definition entity manager and got null, so the operation requiring a definition (e.g. correlating a start message to a process) cannot proceed.

Source

Thrown at modules/flowable-engine/src/main/java/org/flowable/engine/impl/cmd/AbstractProcessStartEventSubscriptionCmd.java:73

    protected void checkEventModelCorrelationParameter(EventModel eventModel, String correlationParameterName) {
        Collection<EventPayload> correlationParameters = eventModel.getCorrelationParameters();
        for (EventPayload correlationParameter : correlationParameters) {
            if (correlationParameter.getName().equals(correlationParameterName)) {
                return;
            }
        }
        throw new FlowableIllegalArgumentException("There is no correlation parameter with name '" + correlationParameterName + "' defined in event model "
            + "with key '" + eventModel.getKey() + "'. You can only subscribe for an event with a combination of valid correlation parameters.");
    }

    protected ProcessDefinition getLatestProcessDefinitionByKey(String processDefinitionKey, String tenantId, CommandContext commandContext) {
        ProcessDefinitionEntityManager processDefinitionEntityManager = CommandContextUtil.getProcessDefinitionEntityManager(commandContext);
        ProcessDefinition processDefinition = null;
        if (processDefinitionKey != null && (tenantId == null || ProcessEngineConfiguration.NO_TENANT_ID.equals(tenantId))) {
            processDefinition = processDefinitionEntityManager.findLatestProcessDefinitionByKey(processDefinitionKey);

            if (processDefinition == null) {
                throw new FlowableObjectNotFoundException("No process definition found for key '" + processDefinitionKey + "'", ProcessDefinition.class);
            }

        } else if (processDefinitionKey != null && tenantId != null && !ProcessEngineConfiguration.NO_TENANT_ID.equals(tenantId)) {

            processDefinition = processDefinitionEntityManager.findLatestProcessDefinitionByKeyAndTenantId(processDefinitionKey, tenantId);

            if (processDefinition == null) {
                ProcessEngineConfigurationImpl processEngineConfiguration = CommandContextUtil.getProcessEngineConfiguration(commandContext);
                if (processEngineConfiguration.isFallbackToDefaultTenant()) {
                    String defaultTenant = processEngineConfiguration.getDefaultTenantProvider().getDefaultTenant(tenantId, ScopeTypes.BPMN, processDefinitionKey);
                    if (StringUtils.isNotEmpty(defaultTenant)) {
                        processDefinition = processDefinitionEntityManager.findLatestProcessDefinitionByKeyAndTenantId(processDefinitionKey, defaultTenant);
                        
                    } else {
                        processDefinition = processDefinitionEntityManager.findLatestProcessDefinitionByKey(processDefinitionKey);
                    }
                    
                    if (processDefinition == null) {

View on GitHub (pinned to d6d39ce1c6)

Solutions

Deploy a BPMN process definition whose process id equals the requested key before calling the API
Verify the exact key via repositoryService.createProcessDefinitionQuery().latestVersion().list() and correct the key string
Check you are not passing the process name or a different environment's key
If using tenants, pass the tenantId so the tenant-scoped lookup path is used

Example fix

// before
runtimeService.createChangeActivityStateBuilder()... // correlation with key 'orderProcess' that was never deployed
// after
repositoryService.createDeployment().addClasspathResource("order-process.bpmn20.xml").deploy();
// then use the same key as the BPMN <process id="orderProcess">

Defensive patterns

Strategy: validation

Validate before calling

long count = repositoryService.createProcessDefinitionQuery().processDefinitionKey(key).count();
if (count == 0) throw new IllegalStateException("Process definition key not deployed: " + key);

Try / catch

try {
    // start/correlate by key
} catch (FlowableObjectNotFoundException e) {
    // log missing key, optionally auto-deploy, then rethrow or skip
}

Prevention

Deploy all BPMN resources at application startup and assert query counts
Use constants for process keys instead of inline strings
Add an integration test correlating every process start key

When it happens

Trigger: Calling APIs built on AbstractProcessStartEventSubscriptionCmd (e.g. message/event start subscription correlation) with a processDefinitionKey that has no latest deployed definition, while tenantId is null or equals ProcessEngineConfiguration.NO_TENANT_ID.

Common situations: Typo in the process key; process definition never deployed; all definitions with that key were deleted from ACT_RE_PROCDEF; querying before deployment finished in another transaction/environment.

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/7b55a9d3975440f2. Report an issue: GitHub.