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

flowable/flowable-engine · error · ActivitiObjectNotFoundException

No process definition found for key '<processDefinitionKey>'

Error message

No process definition found for key '<processDefinitionKey>'

What it means

Thrown by StartProcessInstanceCmd.execute() as ActivitiObjectNotFoundException when starting by key with no tenant (or the special NO_TENANT_ID) and no deployed process definition exists with that latest key. The engine looked up the latest definition by key and found nothing.

Source

Thrown at modules/flowable5-engine/src/main/java/org/activiti/engine/impl/cmd/StartProcessInstanceCmd.java:85

    }

    @Override
    public ProcessInstance execute(CommandContext commandContext) {
        DeploymentManager deploymentManager = commandContext
                .getProcessEngineConfiguration()
                .getDeploymentManager();

        // Find the process definition
        ProcessDefinition processDefinition = null;
        if (processDefinitionId != null) {
            processDefinition = deploymentManager.findDeployedProcessDefinitionById(processDefinitionId);
            if (processDefinition == null) {
                throw new ActivitiObjectNotFoundException("No process definition found for id = '" + processDefinitionId + "'", ProcessDefinition.class);
            }
        } else if (processDefinitionKey != null && (tenantId == null || ProcessEngineConfiguration.NO_TENANT_ID.equals(tenantId))) {
            processDefinition = deploymentManager.findDeployedLatestProcessDefinitionByKey(processDefinitionKey);
            if (processDefinition == null) {
                throw new ActivitiObjectNotFoundException("No process definition found for key '" + processDefinitionKey + "'", ProcessDefinition.class);
            }
        } else if (processDefinitionKey != null && tenantId != null && !ProcessEngineConfiguration.NO_TENANT_ID.equals(tenantId)) {
            processDefinition = deploymentManager.findDeployedLatestProcessDefinitionByKeyAndTenantId(processDefinitionKey, tenantId);
            if (processDefinition == null) {
                throw new ActivitiObjectNotFoundException("No process definition found for key '" + processDefinitionKey + "' for tenant identifier " + tenantId, ProcessDefinition.class);
            }
        } else {
            throw new ActivitiIllegalArgumentException("processDefinitionKey and processDefinitionId are null");
        }

        // Do not start process a process instance if the process definition is suspended
        if (deploymentManager.isProcessDefinitionSuspended(processDefinition.getId())) {
            throw new ActivitiException("Cannot start process instance. Process definition "
                    + processDefinition.getName() + " (id = " + processDefinition.getId() + ") is suspended");
        }

        // Start the process instance
        ExecutionEntity processInstance = ((ProcessDefinitionEntity) processDefinition).createProcessInstance(businessKey);

View on GitHub (pinned to d6d39ce1c6)

Solutions

Check the definition exists: RepositoryService.createProcessDefinitionQuery().processDefinitionKey(key).list() and fix the key if empty.
Ensure the BPMN process id (or key attribute) matches the key used in startProcessInstanceByKey.
Deploy the definition first (RepositoryService.createDeployment().addClasspathResource(...).deploy()).
If the definition is tenant-scoped, call startProcessInstanceByKey(key, tenantId) so the tenant-aware lookup runs.

Example fix

// before
runtimeService.startProcessInstanceByKey("OrderProcess"); // wrong case, nothing deployed under this key
// after
// BPMN: <process id="orderProcess" ...>
runtimeService.startProcessInstanceByKey("orderProcess");

Defensive patterns

Strategy: validation

Validate before calling

if (repositoryService.createProcessDefinitionQuery()
        .processDefinitionKey(definitionKey).count() == 0) {
    throw new IllegalStateException("No definition deployed for key: " + definitionKey);
}

Try / catch

try {
    return runtimeService.startProcessInstanceByKey(definitionKey, vars);
} catch (ActivitiObjectNotFoundException e) {
    log.error("Process definition key '{}' not deployed", definitionKey, e);
    throw new DeploymentMissingException(definitionKey, e);
}

Prevention

Make deployment part of startup/tests so keys always exist before runtime use
Assert the BPMN <process id> equals the key string used in code
Add a smoke test that starts each process key in a test DB
Log available keys (ProcessDefinitionQuery list) when the lookup fails

When it happens

Trigger: RuntimeService.startProcessInstanceByKey(key) where the key is misspelled, the BPMN processId differs from the expected key, or no deployment containing that process was ever made to the default tenant.

Common situations: Deploying a BPMN file whose <process id="..."> doesn't match the key used in code; forgetting to deploy the process definition before runtime use; deploying to a tenant but starting without tenantId; case mismatch in the key.

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