flowable/flowable-engine · error · ActivitiObjectNotFoundException

no processes deployed with key '<processDefinitionKey>'

Error message

no processes deployed with key '<processDefinitionKey>'

What it means

ActivitiObjectNotFoundException thrown by DeploymentManager.findDeployedLatestProcessDefinitionByKey when no process definition with the given key is deployed. The entity manager's findLatestProcessDefinitionByKey returns null and the manager converts it into this descriptive error. It means the workflow key being referenced has no deployed (latest) version in this engine.

Source

Thrown at modules/flowable5-engine/src/main/java/org/activiti/engine/impl/persistence/deploy/DeploymentManager.java:150

                }
            }

            // Convert the bpmn 2.0 xml to a bpmn model
            BpmnXMLConverter bpmnXMLConverter = new BpmnXMLConverter();
            bpmnModel = bpmnXMLConverter.convertToBpmnModel(new BytesStreamSource(resource.getBytes()), false, false);
            bpmnModelCache.add(processDefinition.getId(), bpmnModel);
        }
        return bpmnModel;
    }

    public ProcessDefinition findDeployedLatestProcessDefinitionByKey(String processDefinitionKey) {
        ProcessDefinition processDefinition = Context
                .getCommandContext()
                .getProcessDefinitionEntityManager()
                .findLatestProcessDefinitionByKey(processDefinitionKey);

        if (processDefinition == null) {
            throw new ActivitiObjectNotFoundException("no processes deployed with key '" + processDefinitionKey + "'", ProcessDefinition.class);
        }
        processDefinition = resolveProcessDefinition(processDefinition).getProcessDefinition();
        return processDefinition;
    }

    public ProcessDefinition findDeployedLatestProcessDefinitionByKeyAndTenantId(String processDefinitionKey, String tenantId) {
        ProcessDefinition processDefinition = Context
                .getCommandContext()
                .getProcessDefinitionEntityManager()
                .findLatestProcessDefinitionByKeyAndTenantId(processDefinitionKey, tenantId);
        if (processDefinition == null) {
            throw new ActivitiObjectNotFoundException("no processes deployed with key '" + processDefinitionKey + "' for tenant identifier '" + tenantId + "'", ProcessDefinition.class);
        }
        processDefinition = resolveProcessDefinition(processDefinition).getProcessDefinition();
        return processDefinition;
    }

    public ProcessDefinition findDeployedProcessDefinitionByKeyAndVersion(String processDefinitionKey, Integer processDefinitionVersion) {

View on GitHub (pinned to d6d39ce1c6)

Solutions

  1. Deploy the BPMN process with that key before starting instances: repositoryService.createDeployment().addClasspathResource(...).deploy()
  2. Check the key: it must match the id attribute of the <process> element in the BPMN XML
  3. Verify with repositoryService.createProcessDefinitionQuery().processDefinitionKey(key).count() > 0
  4. Confirm you are connected to the correct database/tenant where the process is deployed

Example fix

// before
runtimeService.startProcessInstanceByKey("OrderProcess"); // key never deployed
// after
if (repositoryService.createProcessDefinitionQuery().processDefinitionKey("OrderProcess").count() > 0) {
    runtimeService.startProcessInstanceByKey("OrderProcess");
} else {
    repositoryService.createDeployment().addClasspathResource("order-process.bpmn20.xml").deploy();
}
Defensive patterns

Strategy: validation

Validate before calling

if (repositoryService.createProcessDefinitionQuery()
        .processDefinitionKey(key).latestVersion().count() == 0) {
    throw new IllegalStateException("No deployed process with key: " + key);
}

Try / catch

try {
    return runtimeService.startProcessInstanceByKey(key);
} catch (ActivitiObjectNotFoundException e) {
    // deploy the process or route to a dead-letter handler
}

Prevention

When it happens

Trigger: Calling RuntimeService.startProcessInstanceByKey(key) or RepositoryService...latestProcessDefinitionByKey where the key was never deployed, was misspelled, or all deployments with that key were deleted.

Common situations: Typos in the key vs the id attribute in the BPMN XML, deploying to a test engine but running against production, or deleting a deployment removes the only version of the process.

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