flowable/flowable-engine · error · ActivitiObjectNotFoundException

Cannot find process definition for id

Error message

Cannot find process definition for id '${processDefinitionId}'

What it means

findProcessDefinition() looks up the definition by id via ProcessDefinitionEntityManager.findProcessDefinitionById(). If no definition exists for the supplied id, it throws ActivitiObjectNotFoundException with ProcessDefinition.class as the missing object type. The id is well-formed but does not correspond to any deployed process definition.

Solutions

  1. Verify the id exists: repositoryService.createProcessDefinitionQuery().processDefinitionId(id).singleResult() before suspending/activating.
  2. Prefer suspend/activate by key (latest version) instead of a pinned id, so redeployments don't invalidate it.
  3. List available definitions (createProcessDefinitionQuery().list()) and use the correct id for the target environment.
  4. Check tenant/database configuration if the definition was deployed elsewhere.

Example fix

// before
repositoryService.suspendProcessDefinitionById("orderProcess:1:999"); // stale id
// after
ProcessDefinition pd = repositoryService.createProcessDefinitionQuery()
    .processDefinitionKey("orderProcess").latestVersion().singleResult();
repositoryService.suspendProcessDefinitionById(pd.getId());
Defensive patterns

Strategy: validation

Validate before calling

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

Try / catch

try { repositoryService.suspendProcessDefinitionById(id); } catch (ActivitiObjectNotFoundException e) { if (e.getObjectClass() == ProcessDefinition.class) { log.error("No definition for id {} — check environment/deployment", id); } throw e; }

Prevention

When it happens

Trigger: Calling suspend/activate by id (SetProcessDefinitionStateCmd with processDefinitionId set) where the id is stale, misspelled, from a different database/tenant, or the deployment was deleted.

Common situations: Hardcoded definition ids copied between environments (test id used in prod); definition redeployed producing a new id; cascade suspension by key attempted with an old id; multi-database setups referencing the wrong schema.

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/c1cfaeeb72e1a6f6. Report an issue: GitHub.

Appendix: source

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

        // If process definition is already provided (eg. when command is called through the DeployCmd)
        // we don't need to do an extra database fetch and we can simply return it, wrapped in a list
        if (processDefinitionEntity != null) {
            return Collections.singletonList(processDefinitionEntity);
        }

        // Validation of input parameters
        if (processDefinitionId == null && processDefinitionKey == null) {
            throw new ActivitiIllegalArgumentException("Process definition id or key cannot be null");
        }

        List<ProcessDefinitionEntity> processDefinitionEntities = new ArrayList<>();
        ProcessDefinitionEntityManager processDefinitionManager = commandContext.getProcessDefinitionEntityManager();

        if (processDefinitionId != null) {

            ProcessDefinitionEntity processDefinitionEntity = processDefinitionManager.findProcessDefinitionById(processDefinitionId);
            if (processDefinitionEntity == null) {
                throw new ActivitiObjectNotFoundException("Cannot find process definition for id '" + processDefinitionId + "'", ProcessDefinition.class);
            }
            processDefinitionEntities.add(processDefinitionEntity);

        } else {

            ProcessDefinitionQueryImpl query = new ProcessDefinitionQueryImpl(commandContext).processDefinitionKey(processDefinitionKey);

            if (tenantId == null || ProcessEngineConfiguration.NO_TENANT_ID.equals(tenantId)) {
                query.processDefinitionWithoutTenantId();
            } else {
                query.processDefinitionTenantId(tenantId);
            }

            List<ProcessDefinition> processDefinitions = query.list();
            if (processDefinitions.isEmpty()) {
                throw new ActivitiException("Cannot find process definition for key '" + processDefinitionKey + "'");
            }

View on GitHub (pinned to d6d39ce1c6)