flowable/flowable-engine · error · FlowableObjectNotFoundException

No process definition found for key '{processDefinitionKey}'

Error message

No process definition found for key '{processDefinitionKey}'. Fallback to default tenant was also applied.

What it means

This FlowableObjectNotFoundException means the process definition key was not found even after falling back to the default tenant. getLatestProcessDefinitionByKey first tried the key with the given tenantId, then retried with findLatestProcessDefinitionByKey; both returned null.

Source

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

            }

        } else if (processDefinitionKey != null && tenantId != null && !ProcessEngineConfiguration.NO_TENANT_ID.equals(tenantId)) {

            processDefinition = processDefinitionEntityManager.findLatestProcessDefinitionByKeyAndTenantId(processDefinitionKey, tenantId);

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

View on GitHub (pinned to d6d39ce1c6)

Solutions

Deploy the process definition with the correct tenantId (deployment.tenantId(...))
Verify with repositoryService.createProcessDefinitionQuery().processDefinitionTenantId(tenantId, isEqual).list()
Correct the tenantId string passed to the API
Check the fallback: if the definition exists without tenant, pass NO_TENANT_ID instead

Example fix

// before
repositoryService.createDeployment().addClasspathResource("p.bpmn").tenantId("tenantA").deploy(); // but lookup uses "tenant-a"
// after
String tenantId = "tenantA"; // match deployment tenant exactly

Defensive patterns

Strategy: validation

Validate before calling

boolean exists = !repositoryService.createProcessDefinitionQuery()
    .processDefinitionKey(key).processDefinitionTenantId(tenantId, true).list().isEmpty();
if (!exists) throw new IllegalStateException("No definition for key=" + key + " tenant=" + tenantId);

Try / catch

try {
    // tenant-scoped start
} catch (FlowableObjectNotFoundException e) {
    // fall back to default tenant lookup or surface a clear tenant mismatch message
}

Prevention

Centralize tenant ids in one enum/config; never free-type tenant strings
Ensure deployments always set tenantId in multi-tenant apps
Log deployed key+tenant pairs on startup for troubleshooting

When it happens

Trigger: Calling a start-event subscription command with both processDefinitionKey and a specific tenantId where no definition exists for that tenant and none exists without a tenant either.

Common situations: Definitions deployed under a different tenant id than the one passed; multi-tenant deployment scripts skipped this tenant; tenantId casing mismatch.

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