flowable/flowable-engine · error · ActivitiException

Cannot find process definition for key '${processDefinitionK

Error message

Cannot find process definition for key '${processDefinitionKey}'

What it means

Thrown by AbstractSetProcessDefinitionStateCmd.findProcessDefinition when a query for process definitions by the given key (and optional tenant) returns no rows. The command cannot change the state (suspension/activation) of a definition that does not exist, so it fails fast with an ActivitiException.

Source

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

            ProcessDefinitionEntity processDefinitionEntity = processDefinitionManager.findProcessDefinitionById(processDefinitionId);
            if (processDefinitionEntity == null) {
                throw new ActivitiObjectNotFoundException("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 ActivitiException("Cannot find process definition for key '" + processDefinitionKey + "'");
            }

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

        }
        return processDefinitionEntities;
    }

    protected void createTimerForDelayedExecution(CommandContext commandContext, List<ProcessDefinitionEntity> processDefinitions) {
        for (ProcessDefinitionEntity processDefinition : processDefinitions) {
            TimerJobEntity timer = new TimerJobEntity();
            timer.setJobType(Job.JOB_TYPE_TIMER);
            timer.setRevision(1);
            timer.setProcessDefinitionId(processDefinition.getId());

            // Inherit tenant identifier (if applicable)

View on GitHub (pinned to d6d39ce1c6)

Solutions

1. Verify the processDefinitionKey matches the <process id="..."> in the BPMN XML of a deployed definition (query ACT_RE_PROCDEF or RepositoryService.createProcessDefinitionQuery().processDefinitionKey(key).list()).
2. If using tenant id, confirm the definition is deployed with that exact tenantId; use activateProcessDefinitionByKey(key).processDefinitionTenantId(...) consistently with the deployment.
3. Deploy the missing process definition first via RepositoryService.createDeployment().addClasspathResource(...).tenantId(...).deploy().
4. Fix typos/case in the key; keys are matched exactly.

Example fix

// before
runtimeService.suspendProcessDefinitionByKey("ordeProcess");
// after
runtimeService.suspendProcessDefinitionByKey("orderProcess"); // key matches deployed BPMN <process id="orderProcess">

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

try {
    runtimeService.suspendProcessDefinitionByKey(key);
} catch (ActivitiException e) {
    if (e.getMessage() != null && e.getMessage().startsWith("Cannot find process definition for key")) {
        logger.warn("Definition {} not deployed", key);
    } else { throw e; }
}

When it happens

Trigger: Calling RuntimeService.activateProcessDefinitionByKey/suspendProcessDefinitionByKey (or by key and tenant id) with a processDefinitionKey that has no deployed definition, a typo in the key, or a tenantId that does not match the deployment's tenant.

Common situations: Deployed the process under a different key than the one referenced in code/config; multi-tenant setup where the definition is deployed to tenant A but queried with tenant B (or null vs explicit tenant mismatch); running against a fresh database where the deployment never happened.

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

• Cannot find processInstance for id '${executionId}'.
• Cannot find process definition with id
• Process Definition '' not found
• No process definition found for id ''
• No process definition found for id '<processDefinitionId>'

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