flowable/flowable-engine · error · FlowableObjectNotFoundException

No process definition found for id =

Error message

No process definition found for id = '${processDefinitionId}'

What it means

Flowable throws this FlowableObjectNotFoundException when the process definition id supplied to SetProcessDefinitionCategoryCmd is well-formed but no matching ProcessDefinitionEntity exists in the repository. The exception carries ProcessDefinition.class as the object reference, indicating which entity type was not found. The category update does not happen.

Solutions

1. Look up the current id via RepositoryService.createProcessDefinitionQuery().processDefinitionKey(key).latestVersion().singleResult() and use its getId()
2. Verify the database/tenant matches where the definition was deployed
3. Re-deploy the BPMN resource if the definition was deleted
4. Catch FlowableObjectNotFoundException and treat it as a missing-definition condition if that is expected

Example fix

// before
repositoryService.setProcessDefinitionCategory("process:1:4", "production"); // stale id
// after
ProcessDefinition def = repositoryService.createProcessDefinitionQuery()
    .processDefinitionKey("process").latestVersion().singleResult();
repositoryService.setProcessDefinitionCategory(def.getId(), "production");

ProcessDefinition def = repositoryService.createProcessDefinitionQuery()
    .processDefinitionId(processDefinitionId).singleResult();
if (def == null) {
    throw new IllegalStateException("No process definition for id " + processDefinitionId);
}

boolean processDefinitionExists(String id) {
    return id != null && repositoryService.createProcessDefinitionQuery()
        .processDefinitionId(id).count() > 0;
}

try {
    repositoryService.setProcessDefinitionCategory(id, category);
} catch (FlowableObjectNotFoundException e) {
    log.warn("Process definition not found: {}", id, e);
}

When it happens

Trigger: Calling RepositoryService.setProcessDefinitionCategory(id, category) with an id that was deleted, never existed, or was mistyped; the definition was removed by deleteDeployment with cascade; querying against a different database or tenant.

Common situations: Stale ids cached after re-deployment (new version gets a new id); deleteDeployment cascading away definitions; copying ids between environments; typo in a config file storing the 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 case definition for id:
• Cannot find process definition for id
• Cannot find process definition for key
• Cannot find process definition with id " +…
• Cannot find process definition with id

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

Appendix: source

Thrown at modules/flowable-engine/src/main/java/org/flowable/engine/impl/cmd/SetProcessDefinitionCategoryCmd.java:55

    protected String category;

    public SetProcessDefinitionCategoryCmd(String processDefinitionId, String category) {
        this.processDefinitionId = processDefinitionId;
        this.category = category;
    }

    @Override
    public Void execute(CommandContext commandContext) {

        if (processDefinitionId == null) {
            throw new FlowableIllegalArgumentException("Process definition id is null");
        }

        ProcessEngineConfigurationImpl processEngineConfiguration = CommandContextUtil.getProcessEngineConfiguration(commandContext);
        ProcessDefinitionEntity processDefinition = processEngineConfiguration.getProcessDefinitionEntityManager().findById(processDefinitionId);

        if (processDefinition == null) {
            throw new FlowableObjectNotFoundException("No process definition found for id = '" + processDefinitionId + "'", ProcessDefinition.class);
        }

        if (Flowable5Util.isFlowable5ProcessDefinition(processDefinition, commandContext)) {
            Flowable5CompatibilityHandler compatibilityHandler = Flowable5Util.getFlowable5CompatibilityHandler();
            compatibilityHandler.setProcessDefinitionCategory(processDefinitionId, category);
            return null;
        }

        // Update category
        processDefinition.setCategory(category);

        // Remove process definition from cache, it will be refetch later
        DeploymentCache<ProcessDefinitionCacheEntry> processDefinitionCache = processEngineConfiguration.getProcessDefinitionCache();
        if (processDefinitionCache != null) {
            processDefinitionCache.remove(processDefinitionId);
        }

        FlowableEventDispatcher eventDispatcher = processEngineConfiguration.getEventDispatcher();

View on GitHub (pinned to d6d39ce1c6)