What causes "No process definition found for id = ' '" in flowable/flowable-engine?

flowable/flowable-engine · error · ActivitiObjectNotFoundException

No process definition found for id = '<processDefinitionId>'

Error message

No process definition found for id = '<processDefinitionId>'

What it means

Thrown by StartProcessInstanceCmd.execute() as ActivitiObjectNotFoundException when a process definition id is supplied but no deployed definition with that id exists in the deployment cache/repository. The engine cannot locate the definition needed to instantiate a new process instance, and ProcessDefinition.class is attached as the missing object type.

Source

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

                processInstanceBuilder.getBusinessKey(),
                processInstanceBuilder.getVariables(),
                processInstanceBuilder.getTenantId());
        this.processInstanceName = processInstanceBuilder.getProcessInstanceName();
        this.transientVariables = processInstanceBuilder.getTransientVariables();
    }

    @Override
    public ProcessInstance execute(CommandContext commandContext) {
        DeploymentManager deploymentManager = commandContext
                .getProcessEngineConfiguration()
                .getDeploymentManager();

        // Find the process definition
        ProcessDefinition processDefinition = null;
        if (processDefinitionId != null) {
            processDefinition = deploymentManager.findDeployedProcessDefinitionById(processDefinitionId);
            if (processDefinition == null) {
                throw new ActivitiObjectNotFoundException("No process definition found for id = '" + processDefinitionId + "'", ProcessDefinition.class);
            }
        } else if (processDefinitionKey != null && (tenantId == null || ProcessEngineConfiguration.NO_TENANT_ID.equals(tenantId))) {
            processDefinition = deploymentManager.findDeployedLatestProcessDefinitionByKey(processDefinitionKey);
            if (processDefinition == null) {
                throw new ActivitiObjectNotFoundException("No process definition found for key '" + processDefinitionKey + "'", ProcessDefinition.class);
            }
        } else if (processDefinitionKey != null && tenantId != null && !ProcessEngineConfiguration.NO_TENANT_ID.equals(tenantId)) {
            processDefinition = deploymentManager.findDeployedLatestProcessDefinitionByKeyAndTenantId(processDefinitionKey, tenantId);
            if (processDefinition == null) {
                throw new ActivitiObjectNotFoundException("No process definition found for key '" + processDefinitionKey + "' for tenant identifier " + tenantId, ProcessDefinition.class);
            }
        } else {
            throw new ActivitiIllegalArgumentException("processDefinitionKey and processDefinitionId are null");
        }

        // Do not start process a process instance if the process definition is suspended
        if (deploymentManager.isProcessDefinitionSuspended(processDefinition.getId())) {
            throw new ActivitiException("Cannot start process instance. Process definition "

View on GitHub (pinned to d6d39ce1c6)

Solutions

Query the actual id with RepositoryService.createProcessDefinitionQuery().processDefinitionKey(key).latestVersion().singleResult() and use that id.
Prefer starting by key (startProcessInstanceByKey) so the latest active version is resolved automatically.
Verify the definition exists in the connected DB/schema and that the engine points at the right database and tenant.
Fix application data holding stale definition ids; re-resolve ids after each redeploy since versions/ids change.

Example fix

// before
runtimeService.startProcessInstanceById("orderProcess:1:hardcoded-id", vars); // stale id
// after
ProcessDefinition pd = repositoryService.createProcessDefinitionQuery()
    .processDefinitionKey("orderProcess").latestVersion().singleResult();
runtimeService.startProcessInstanceById(pd.getId(), vars);

Defensive patterns

Strategy: validation

Validate before calling

ProcessDefinition pd = repositoryService.createProcessDefinitionQuery()
    .processDefinitionId(definitionId).singleResult();
if (pd == null) {
    throw new IllegalStateException("Unknown process definition id: " + definitionId);
}

Try / catch

try {
    return runtimeService.startProcessInstanceById(definitionId, vars);
} catch (ActivitiObjectNotFoundException e) {
    // check missing object type and fall back to key lookup
    if (ProcessDefinition.class.equals(e.getObjectClass())) {
        return runtimeService.startProcessInstanceByKey(knownKey, vars);
    }
    throw e;
}

Prevention

Never hardcode definition ids — always resolve via ProcessDefinitionQuery
Prefer startProcessInstanceByKey so version changes don't break callers
Re-resolve ids after every deployment or deleteDeployment
Verify both engines point at the same database when sharing ids across environments

When it happens

Trigger: RuntimeService.startProcessInstanceById(badId) where the id is wrong, malformed, belongs to another engine/database, or the deployment was deleted; stale ids persisted in application data pointing to an undeployed definition.

Common situations: Copying a definition id from a different environment (test vs prod) or different database schema; definition deleted via RepositoryService.deleteDeployment while callers still reference its id; pointing at a shared DB where another engine's definitions live.

Understand the failure class

Background: "Not found" and "does not exist" errors: why "Task not found", "No such folder", and "Can't find" fire when a lookup comes back empty — this error's family across 14 libraries.

Related errors

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