flowable/flowable-engine · error · FlowableObjectNotFoundException

No process definition found for key '${processDefinitionKey}

Error message

No process definition found for key '${processDefinitionKey}'

What it means

A FlowableObjectNotFoundException thrown by resolveProcessDefinition when no ProcessDefinition entity exists for the given key (with the given tenant, or no tenant). This is the no-tenant / NO_TENANT_ID branch of the three-way lookup failure in ProcessInstanceHelper.

Source

Thrown at modules/flowable-engine/src/main/java/org/flowable/engine/impl/util/ProcessInstanceHelper.java:423

                } else {
                    processDefinition = processDefinitionEntityManager
                            .findLatestProcessDefinitionByKey(processDefinitionKey);
                }
            }
        } else {
            if (parentDeploymentId != null) {
                processDefinition = processDefinitionEntityManager
                        .findProcessDefinitionByParentDeploymentAndKey(parentDeploymentId, processDefinitionKey);
            }
            if (processDefinition == null) {
                processDefinition = processDefinitionEntityManager
                        .findLatestProcessDefinitionByKey(processDefinitionKey);
            }
        }

        if (processDefinition == null) {
            if (tenantId == null || ProcessEngineConfiguration.NO_TENANT_ID.equals(tenantId)) {
                throw new FlowableObjectNotFoundException(
                        "No process definition found for key '" + processDefinitionKey + "'", ProcessDefinition.class);
            } else if (fallbackToDefaultTenant) {
                throw new FlowableObjectNotFoundException(
                        "No process definition found for key '" + processDefinitionKey + "'. Fallback to default tenant was also applied.", ProcessDefinition.class);
            } else {
                throw new FlowableObjectNotFoundException(
                        "Process definition with key '" + processDefinitionKey + "' and tenantId '" + tenantId + "' was not found", ProcessDefinition.class);
            }
        }

        return processDefinition;
    }

    public void callCaseInstanceStateChangeCallbacks(CommandContext commandContext, ProcessInstance processInstance, String oldState, String newState) {
        if (processInstance.getCallbackId() != null && processInstance.getCallbackType() != null) {
            Map<String, List<RuntimeInstanceStateChangeCallback>> caseInstanceCallbacks = CommandContextUtil
                    .getProcessEngineConfiguration(commandContext).getProcessInstanceStateChangedCallbacks();

View on GitHub (pinned to d6d39ce1c6)

Solutions

1. Deploy the BPMN file: repositoryService.createDeployment().addClasspathResource("...bpmn20.xml").deploy().
2. Verify the key equals the <process id="..."> attribute via a ProcessDefinitionQuery on processDefinitionKey.
3. If the process is tenant-scoped, call the startProcessInstance...ByKey overload with the correct tenantId.
4. Confirm you are connected to the database/environment where the definition exists.

Example fix

// before
runtimeService.startProcessInstanceByKey("orderProcess", vars); // never deployed
// after
repositoryService.createDeployment().addClasspathResource("processes/order-process.bpmn20.xml").tenantId("acme").deploy();
runtimeService.startProcessInstanceByKey("orderProcess", "acme", vars);

ProcessDefinition def = repositoryService.createProcessDefinitionQuery().processDefinitionKey(key).latestVersion().singleResult();
if (def == null) {
    throw new IllegalStateException("Process '" + key + "' not deployed — deploy the BPMN resource before starting");
}

try {
    return runtimeService.startProcessInstanceByKey(key, vars);
} catch (FlowableObjectNotFoundException e) {
    if (e.getMessage().startsWith("No process definition found for key")) {
        repositoryService.createDeployment().addClasspathResource("processes/" + key + ".bpmn20.xml").deploy();
        return runtimeService.startProcessInstanceByKey(key, vars);
    }
    throw e;
}

When it happens

Trigger: RuntimeService.startProcessInstanceByKey(key, ...) (including message/signal paths) when findLatestProcessDefinitionByKey returns null — the process was never deployed, the key is misspelled, or the key only exists under a tenant id while none was supplied.

Common situations: Deploying to a tenant-aware engine but calling without tenantId; typo in the key vs the <process id="...">; environment (test vs prod) where the process was never deployed; engine started against an empty/fresh database.

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}'
• Cannot find process definition for key '{processDefinitionKe
• No process definition found for key '${processDefinitionKey}
• Process definition with key '${processDefinitionKey}' and te

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