flowable/flowable-engine · error · FlowableObjectNotFoundException

Cannot find process definition for id

Error message

Cannot find process definition for id '{processDefinitionId}'

What it means

When a processDefinitionId is provided to findProcessDefinition, the command loads it via the entity manager; if no row matches, this FlowableObjectNotFoundException is thrown. The id must reference an existing, deployed process definition.

Solutions

1. Resolve the id at runtime by key: createProcessDefinitionQuery().processDefinitionKey(key).latestVersion().singleResult().getId()
2. Validate the id with createProcessDefinitionQuery().processDefinitionId(id).singleResult() before executing the state change
3. Sync configuration across environments or store keys (not ids) in config

Example fix

// before
managementService.activateProcessDefinitionById("orderProcess:2:77").activate(); // deleted after redeploy
// after
String id = repositoryService.createProcessDefinitionQuery().processDefinitionKey("orderProcess").latestVersion().singleResult().getId();
managementService.activateProcessDefinitionById(id).activate();

ProcessDefinition pd = repositoryService.createProcessDefinitionQuery().processDefinitionId(id).singleResult();
if (pd == null) throw new IllegalStateException("Cannot suspend: unknown definition id " + id);

try {
    managementService.suspendProcessDefinitionById(id).suspend();
} catch (FlowableObjectNotFoundException e) {
    // id stale: re-resolve by key and retry
}

When it happens

Trigger: Suspending/activating a process definition by id where the id is stale, belongs to another database, or was deleted.

Common situations: Ids persisted in app config that no longer exist after redeploy; environment mismatch (test id used in prod); definition removed by cleanup jobs.

Understand the failure class

Background: Record Not Found Errors: "not found", RecordNotFound, and "was not found" — what they mean and how to fix them — this error's family across 28 libraries.

Related errors

• No deployed process definition found for id
• Active execution could not be found with activity id
• Batch part with id ' ' does not have a batch part document.
• Batch with id ' ' does not have a batch document.
• Cannot associate execution by id: no execution with id '

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

Appendix: source

Thrown at modules/flowable-engine/src/main/java/org/flowable/engine/impl/cmd/AbstractSetProcessDefinitionStateCmd.java:123

        // If process definition is already provided (eg. when command is called through the DeployCmd)
        // we don't need to do an extra database fetch and we can simply return it, wrapped in a list
        if (processDefinitionEntity != null) {
            return Collections.singletonList(processDefinitionEntity);
        }

        // Validation of input parameters
        if (processDefinitionId == null && processDefinitionKey == null) {
            throw new FlowableIllegalArgumentException("Process definition id or key cannot be null");
        }

        List<ProcessDefinitionEntity> processDefinitionEntities = new ArrayList<>();
        ProcessDefinitionEntityManager processDefinitionManager = CommandContextUtil.getProcessDefinitionEntityManager(commandContext);

        if (processDefinitionId != null) {

            ProcessDefinitionEntity processDefinitionEntity = processDefinitionManager.findById(processDefinitionId);
            if (processDefinitionEntity == null) {
                throw new FlowableObjectNotFoundException("Cannot find process definition for id '" + processDefinitionId + "'", ProcessDefinition.class);
            }
            processDefinitionEntities.add(processDefinitionEntity);

        } else {

            ProcessDefinitionQueryImpl query = new ProcessDefinitionQueryImpl(commandContext).processDefinitionKey(processDefinitionKey);

            if (tenantId == null || ProcessEngineConfiguration.NO_TENANT_ID.equals(tenantId)) {
                query.processDefinitionWithoutTenantId();
            } else {
                query.processDefinitionTenantId(tenantId);
            }

            List<ProcessDefinition> processDefinitions = query.list();
            if (processDefinitions.isEmpty()) {
                throw new FlowableException("Cannot find process definition for key '" + processDefinitionKey + "' and tenant '" + tenantId + "'");
            }

View on GitHub (pinned to d6d39ce1c6)