flowable/flowable-engine · error · FlowableIllegalArgumentException

No deployed process definition found for key '{processDefini

Error message

No deployed process definition found for key '{processDefinitionKey}'.

What it means

This FlowableIllegalArgumentException is a terminal guard in getLatestProcessDefinitionByKey: after all key/tenant lookup branches, processDefinition is still null, meaning no deployed definition exists for the key at all (e.g. processDefinitionKey was non-null but the entity manager returned nothing through any branch).

Source

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

                    } else {
                        processDefinition = processDefinitionEntityManager.findLatestProcessDefinitionByKey(processDefinitionKey);
                    }
                    
                    if (processDefinition == null) {
                        throw new FlowableObjectNotFoundException("No process definition found for key '" + processDefinitionKey +
                            "'. Fallback to default tenant was also applied.", ProcessDefinition.class);
                    }
                    
                } else {
                    throw new FlowableObjectNotFoundException("Process definition with key '" + processDefinitionKey +
                        "' and tenantId '"+ tenantId +"' was not found", ProcessDefinition.class);
                }
            }

        }
        
        if (processDefinition == null) {
            throw new FlowableIllegalArgumentException("No deployed process definition found for key '" + processDefinitionKey + "'.");
        }
        
        return processDefinition;
    }

    protected ProcessDefinition getProcessDefinitionById(String processDefinitionId, CommandContext commandContext) {
        RepositoryService repositoryService = CommandContextUtil.getProcessEngineConfiguration(commandContext).getRepositoryService();

        ProcessDefinition processDefinition = repositoryService.createProcessDefinitionQuery()
            .processDefinitionId(processDefinitionId)
            .singleResult();

        if (processDefinition == null) {
            throw new FlowableIllegalArgumentException("No deployed process definition found for id '" + processDefinitionId + "'.");
        }
        return processDefinition;
    }

View on GitHub (pinned to d6d39ce1c6)

Solutions

Deploy the process definition and confirm it appears in ACT_RE_PROCDEF
Cross-check the key with repositoryService.createProcessDefinitionQuery().processDefinitionKey(key).count()
Point the engine at the correct database (jdbc url / schema) for the environment that has the deployment

Example fix

// before
// assume 'invoice' deployed but DB is dev, deployment was in prod
ProcessDefinition pd = ...; // throws
// after
repositoryService.createDeployment().addClasspathResource("invoice.bpmn20.xml").deploy();

Defensive patterns

Strategy: validation

Validate before calling

if (repositoryService.createProcessDefinitionQuery().processDefinitionKey(key).count() == 0) {
    throw new IllegalStateException("Definition not deployed: " + key);
}

Try / catch

try {
    // operation by key
} catch (FlowableIllegalArgumentException e) {
    if (e.getMessage().contains("No deployed process definition")) {
        // trigger deployment or fail fast with actionable message
    }
}

Prevention

Run engine on the database matching the environment that holds deployments
Auto-deploy on startup (flowable auto-deploy) and verify
Keep keys synchronized between BPMN process id and code constants

When it happens

Trigger: Any invocation of the command where the key-based resolution paths all returned null — effectively no definition deployed for that key regardless of tenant handling.

Common situations: Engine connected to a database from a different environment; deployment rolled back; key mismatch between BPMN process id and the string used in code.

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