flowable/flowable-engine · error · FlowableObjectNotFoundException

Process definition with key '{processDefinitionKey}' and ten

Error message

Process definition with key '{processDefinitionKey}' and tenantId '{tenantId}' was not found

What it means

Flowable throws this when a tenantId was supplied but no process definition exists with that key and tenant, and the fallback-to-default-tenant branch was not applicable/failed to produce a definition. It distinguishes the tenant-scoped miss from the plain key miss.

Source

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

            if (processDefinition == null) {
                ProcessEngineConfigurationImpl processEngineConfiguration = CommandContextUtil.getProcessEngineConfiguration(commandContext);
                if (processEngineConfiguration.isFallbackToDefaultTenant()) {
                    String defaultTenant = processEngineConfiguration.getDefaultTenantProvider().getDefaultTenant(tenantId, ScopeTypes.BPMN, processDefinitionKey);
                    if (StringUtils.isNotEmpty(defaultTenant)) {
                        processDefinition = processDefinitionEntityManager.findLatestProcessDefinitionByKeyAndTenantId(processDefinitionKey, defaultTenant);
                        
                    } else {
                        processDefinition = processDefinitionEntityManager.findLatestProcessDefinitionByKey(processDefinitionKey);
                    }
                    
                    if (processDefinition == null) {
                        throw new FlowableObjectNotFoundException("No process definition found for key '" + processDefinitionKey +
                            "'. Fallback to default tenant was also applied.", ProcessDefinition.class);
                    }
                    
                } else {
                    throw new FlowableObjectNotFoundException("Process definition with key '" + processDefinitionKey +
                        "' and tenantId '"+ tenantId +"' was not found", ProcessDefinition.class);
                }
            }

        }
        
        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)

View on GitHub (pinned to d6d39ce1c6)

Solutions

Deploy the definition with a deployment whose tenantId matches the lookup tenantId
List definitions per tenant with createProcessDefinitionQuery().processDefinitionTenantId(tenantId, true) to confirm the exact tenant
Remove or correct the tenantId argument if the deployment has no tenant
Align tenant propagation in your application (e.g. TenantContext) with deployment tenants

Example fix

// before
getProcessDefinition(key, "acme-tenant"); // deployed without tenant
// after
repositoryService.createDeployment().addClasspathResource("p.bpmn").tenantId("acme-tenant").deploy();

Defensive patterns

Strategy: validation

Validate before calling

if (repositoryService.createProcessDefinitionQuery()
        .processDefinitionKey(key).processDefinitionTenantId(tenantId, true).count() == 0) {
    throw new IllegalStateException("Deploy definition for tenant " + tenantId + " first");
}

Try / catch

try {
    // tenant-scoped call
} catch (FlowableObjectNotFoundException e) {
    // treat as tenant/deployment misconfiguration; alert instead of retry
}

Prevention

Keep a deployment manifest mapping each tenant to its BPMN resources
Automate per-tenant deployments in CI
Validate tenant propagation from request context before engine calls

When it happens

Trigger: Calling getLatestProcessDefinitionByKey via a start-event subscription command with a non-null tenantId (different from NO_TENANT_ID) where findLatestProcessDefinitionByKeyAndTenantId returned an empty result and the subsequent default-tenant lookup also failed (the else branch fires when the fallback path conditions are not met).

Common situations: Definition deployed under the default tenant while a tenantId is passed at lookup; tenant configured in a process instance/query that does not match any deployment tenant.

Understand the failure class

Background: 'Could not be found', 'does not exist', 'not found in database': the resource-not-found family when an ID, slug, key, or URI lookup comes back empty — this error's family across 20 libraries.

Related errors

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