flowable/flowable-engine · error · FlowableException

Cannot find process definition for key '{processDefinitionKe

Error message

Cannot find process definition for key '{processDefinitionKey}' and tenant '{tenantId}'

What it means

When resolving by processDefinitionKey, the command builds a ProcessDefinitionQuery (optionally tenant-scoped) and throws this FlowableException if the result list is empty. Note it does not auto-fallback to the default tenant: the tenant filter, if set, must match.

Source

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

            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 + "'");
            }

            for (ProcessDefinition processDefinition : processDefinitions) {
                processDefinitionEntities.add((ProcessDefinitionEntity) processDefinition);
            }

        }
        return processDefinitionEntities;
    }

    protected void createTimerForDelayedExecution(CommandContext commandContext, List<ProcessDefinitionEntity> processDefinitions) {
        for (ProcessDefinitionEntity processDefinition : processDefinitions) {

            if (Flowable5Util.isFlowable5ProcessDefinition(processDefinition, commandContext)) {
                continue;
            }

            TimerJobService timerJobService = CommandContextUtil.getTimerJobService(commandContext);

View on GitHub (pinned to d6d39ce1c6)

Solutions

1. Deploy the definition with that key, with the matching tenantId
2. Drop or correct processDefinitionTenantId so the query matches the deployment
3. Confirm the key with createProcessDefinitionQuery().processDefinitionKey(key).list()
4. Use byId resolution with the id fetched dynamically if key lookup keeps failing

Example fix

// before
managementService.suspendProcessDefinition().processDefinitionKey("billing").processDefinitionTenantId("acme").suspend(); // deployed as default tenant
// after
managementService.suspendProcessDefinition().processDefinitionKey("billing").suspend();

List<ProcessDefinition> defs = repositoryService.createProcessDefinitionQuery()
    .processDefinitionKey(key)
    .processDefinitionTenantId(tenantId, true).list();
if (defs.isEmpty()) throw new IllegalStateException("No definition for key=" + key + " tenant=" + tenantId);

try {
    managementService.suspendProcessDefinition().processDefinitionKey(key)
        .processDefinitionTenantId(tenantId).suspend();
} catch (FlowableException e) {
    if (e.getMessage().startsWith("Cannot find process definition")) {
        // deploy or drop the tenant filter, then retry
    }
}

When it happens

Trigger: managementService.suspendProcessDefinition().processDefinitionKey(...)[.processDefinitionTenantId(...)] where no latest definition exists for that key/tenant combination.

Common situations: Suspending by key before the first deployment; tenant filter not matching deployment tenant; key renamed in the BPMN model after an upgrade.

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

• Process definition ${processDefinitionKey} was not found in
• No process definition found for key '${processDefinitionKey}
• No process definition found for name:
• No decision found for key <decisionKey>. There was also no f
• No decision found for key <decisionKey>. There was also no f

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