flowable/flowable-engine · error · FlowableIllegalArgumentException

No deployed process definition found for id

Error message

No deployed process definition found for id '{processDefinitionId}'.

What it means

getProcessDefinitionById queried the repository service by exact process definition id and got null, so this FlowableIllegalArgumentException is thrown. A definition id is the key plus version (e.g. 'orderProcess:3:1201'), so it must match an existing row exactly.

Solutions

1. Look up the current id dynamically: repositoryService.createProcessDefinitionQuery().processDefinitionKey(key).latestVersion().singleResult().getId()
2. Verify the id exists via createProcessDefinitionQuery().processDefinitionId(id).singleResult()
3. Replace hand-built ids ('key:version:dbid') with ids returned by the API
4. Suspend/migrate by key instead of by id when the version is unknown

Example fix

// before
setStateCmd.processDefinitionId("orderProcess:1:4"); // stale id
// after
ProcessDefinition pd = repositoryService.createProcessDefinitionQuery().processDefinitionKey("orderProcess").latestVersion().singleResult();
setStateCmd.processDefinitionId(pd.getId());

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

try {
    // byId operation
} catch (FlowableIllegalArgumentException e) {
    // re-resolve id by key/latestVersion and retry once
}

When it happens

Trigger: Passing a processDefinitionId to a set-process-definition-state / start-event command that does not exist, or a malformed id built by string concatenation.

Common situations: Hardcoding an id captured from another database/environment; id format changed between Flowable versions; using the process key where an id is expected.

Understand the failure class

Background: Record Not Found Errors: "not found", RecordNotFound, and "was not found" — what they mean and how to fix them — this error's family across 28 libraries.

Related errors

• Cannot find process definition for id
• Active execution could not be found with activity id
• Batch part with id ' ' does not have a batch part document.
• Batch with id ' ' does not have a batch document.
• Cannot associate execution by id: no execution with id '

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

Appendix: source

Thrown at modules/flowable-engine/src/main/java/org/flowable/engine/impl/cmd/AbstractProcessStartEventSubscriptionCmd.java:119

        }
        
        if (processDefinition == null) {
            throw new FlowableIllegalArgumentException("No deployed process definition found for key '" + processDefinitionKey + "'.");
        }
        
        return processDefinition;
    }

    protected ProcessDefinition getProcessDefinitionById(String processDefinitionId, CommandContext commandContext) {
        RepositoryService repositoryService = CommandContextUtil.getProcessEngineConfiguration(commandContext).getRepositoryService();

        ProcessDefinition processDefinition = repositoryService.createProcessDefinitionQuery()
            .processDefinitionId(processDefinitionId)
            .singleResult();

        if (processDefinition == null) {
            throw new FlowableIllegalArgumentException("No deployed process definition found for id '" + processDefinitionId + "'.");
        }
        return processDefinition;
    }

    protected Process getProcess(String processDefinitionId, CommandContext commandContext) {
        RepositoryService repositoryService = CommandContextUtil.getProcessEngineConfiguration(commandContext).getRepositoryService();
        BpmnModel bpmnModel = repositoryService.getBpmnModel(processDefinitionId);
        return bpmnModel.getMainProcess();
    }

    protected EventModel getEventModel(String eventDefinitionKey, String tenantId, CommandContext commandContext) {
        EventModel eventModel = CommandContextUtil.getEventRepositoryService(commandContext).getEventModelByKey(eventDefinitionKey, tenantId);
        if (eventModel == null) {
            throw new FlowableIllegalArgumentException("Could not find event model with key '" + eventDefinitionKey + "'.");
        }
        return eventModel;
    }

View on GitHub (pinned to d6d39ce1c6)