flowable/flowable-engine · error · ActivitiObjectNotFoundException

No process definition found for key '<processDefinitionKey>'

Error message

No process definition found for key '<processDefinitionKey>' for tenant identifier <tenantId>

What it means

Thrown by StartProcessInstanceCmd.execute() as ActivitiObjectNotFoundException when starting by key with an explicit tenantId and findDeployedLatestProcessDefinitionByKeyAndTenantId returns null. The engine cannot find a deployed latest definition for that key under the given tenant identifier.

Source

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

                .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);

        // now set the variables passed into the start command
        initializeVariables(processInstance);

        // now set processInstance name

View on GitHub (pinned to d6d39ce1c6)

Solutions

1. Deploy the definition for that tenant: repositoryService.createDeployment().tenantId(tenantId).addClasspathResource(...).deploy().
2. Verify with createProcessDefinitionQuery().processDefinitionKey(key).processDefinitionTenantId(tenantId).list() before starting.
3. Check the tenantId string matches exactly the tenant used at deployment time (case-sensitive).
4. If the tenant should share the default definition, start without tenantId (or with NO_TENANT_ID).

Example fix

// before
runtimeService.startProcessInstanceByKey("orderProcess", "tenantA"); // deployed without tenant
// after
repositoryService.createDeployment()
    .tenantId("tenantA")
    .addClasspathResource("processes/orderProcess.bpmn20.xml")
    .deploy();
runtimeService.startProcessInstanceByKey("orderProcess", "tenantA");

if (repositoryService.createProcessDefinitionQuery()
        .processDefinitionKey(definitionKey)
        .processDefinitionTenantId(tenantId).count() == 0) {
    throw new IllegalStateException("No definition for key '" + definitionKey
        + "' and tenant '" + tenantId + "'");
}

try {
    return runtimeService.startProcessInstanceByKey(definitionKey, tenantId, vars);
} catch (ActivitiObjectNotFoundException e) {
    log.error("No definition for key '{}' tenant '{}'", definitionKey, tenantId, e);
    throw e;
}

When it happens

Trigger: RuntimeService.startProcessInstanceByKey(key, tenantId) (or ProcessInstantiationBuilder with tenantId) where no definition with that key is deployed for that tenant — the definition may exist only for the default tenant or another tenant.

Common situations: Multi-tenant deployments where a BPMN resource was deployed without tenantId but started with one (or vice versa); typos in tenant identifiers; tenant onboarding scripts skipped a deployment.

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

• Process definition ${processDefinitionKey} was not found in
• Cannot find process definition for key '{processDefinitionKe
• no processes deployed with key '" + processDefinitionKey + "
• No process definition found for key '${processDefinitionKey}
• No process definition found for key '${processDefinitionKey}

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