flowable/flowable-engine · error · FlowableObjectNotFoundException

No process definition found with id ${processDefinitionId}

Error message

No process definition found with id ${processDefinitionId}

What it means

getProcessDefinitionFromDatabase queries the ProcessDefinitionEntityManager by id; if no row matches, it throws FlowableObjectNotFoundException. This is a typed not-found signal meaning the requested processDefinitionId does not exist in the database (it is not an engine-internal fault).

Source

Thrown at modules/flowable-engine/src/main/java/org/flowable/engine/impl/util/ProcessDefinitionUtil.java:127

    public static BpmnModel getBpmnModelFromCache(String processDefinitionId) {
        ProcessDefinitionCacheEntry cacheEntry = CommandContextUtil.getProcessEngineConfiguration().getProcessDefinitionCache().get(processDefinitionId);
        if (cacheEntry != null) {
            return cacheEntry.getBpmnModel();
        }
        return null;
    }

    public static boolean isProcessDefinitionSuspended(String processDefinitionId) {
        ProcessDefinitionEntity processDefinition = getProcessDefinitionFromDatabase(processDefinitionId);
        return processDefinition.isSuspended();
    }

    public static ProcessDefinitionEntity getProcessDefinitionFromDatabase(String processDefinitionId) {
        ProcessDefinitionEntityManager processDefinitionEntityManager = CommandContextUtil.getProcessEngineConfiguration().getProcessDefinitionEntityManager();
        ProcessDefinitionEntity processDefinition = processDefinitionEntityManager.findById(processDefinitionId);
        if (processDefinition == null) {
            throw new FlowableObjectNotFoundException("No process definition found with id " + processDefinitionId);
        }

        return processDefinition;
    }
}

View on GitHub (pinned to d6d39ce1c6)

Solutions

1. Look up the correct id via repositoryService.createProcessDefinitionQuery().processDefinitionKey(...).latestVersion().singleResult() and use its getId().
2. Check the deployment still exists (it may have been deleted via repositoryService.deleteDeployment with cascade).
3. Verify you are connecting to the database/schema where the definition was actually deployed.
4. Catch FlowableObjectNotFoundException in callers that accept optional definitions.

Example fix

// before
repositoryService.getBpmnModel("procDef:123:999"); // stale id

// after
ProcessDefinition pd = repositoryService.createProcessDefinitionQuery()
    .processDefinitionKey("myProcess").latestVersion().singleResult();
if (pd != null) {
    repositoryService.getBpmnModel(pd.getId());
}

ProcessDefinition pd = repositoryService.createProcessDefinitionQuery()
    .processDefinitionId(processDefinitionId).singleResult();
if (pd == null) {
    throw new IllegalArgumentException("Process definition " + processDefinitionId + " does not exist");
}

try {
    runtimeService.startProcessInstanceById(processDefinitionId);
} catch (FlowableObjectNotFoundException e) {
    log.warn("Definition {} not found; resolving latest version instead", processDefinitionId);
    ProcessDefinition latest = repositoryService.createProcessDefinitionQuery()
        .processDefinitionKey(key).latestVersion().singleResult();
    if (latest != null) runtimeService.startProcessInstanceById(latest.getId());
}

When it happens

Trigger: Calling APIs that resolve a definition (getProcessDefinitionFromDatabase via processDefinition lookups) with an id that is not present in ACT_RE_PROCDEF — deleted deployment, wrong id string, or an id from another engine/database.

Common situations: Application storing process definition ids from an older database; redeployments replacing ids (definition ids include version keys); tenant-specific queries using ids from a different tenant; typo in configuration that references a definition id.

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

• Cannot find process definition with id
• Cannot find process definition with id ${processDefinitionId
• No process definition found for name:
• Process definition ${processDefinitionKey} was not found in
• No process definition found for key '{processDefinitionKey}'

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