flowable/flowable-engine · error · FlowableObjectNotFoundException

Case definition was not found by key '<caseDefinitionKey>'.

Error message

Case definition was not found by key '<caseDefinitionKey>'. Fallback to default tenant was also used.

What it means

resolveCaseDefinition found no case definition for the key, and although a tenant was given and fallback-to-default-tenant was enabled, the fallback also failed. A distinct FlowableObjectNotFoundException is thrown so the caller knows both the tenant-specific lookup and the default-tenant fallback were exhausted.

Source

Thrown at modules/flowable-cmmn-engine/src/main/java/org/flowable/cmmn/engine/impl/runtime/CaseInstanceHelperImpl.java:150

                    caseDefinition = caseDefinitionEntityManager.findLatestCaseDefinitionByKeyAndTenantId(caseDefinitionKey, defaultTenant);
                } else {
                    caseDefinition = caseDefinitionEntityManager.findLatestCaseDefinitionByKey(caseDefinitionKey);
                }
            }
        } else {
            if (parentDeploymentId != null) {
                caseDefinition = caseDefinitionEntityManager.findCaseDefinitionByParentDeploymentAndKey(parentDeploymentId, caseDefinitionKey);
            }
            if (caseDefinition == null) {
                caseDefinition = caseDefinitionEntityManager.findLatestCaseDefinitionByKey(caseDefinitionKey);
            }
        }

        if (caseDefinition == null) {
            if (tenantId == null || CmmnEngineConfiguration.NO_TENANT_ID.equals(tenantId)) {
                throw new FlowableObjectNotFoundException("No case definition found for key " + caseDefinitionKey, CaseDefinition.class);
            } else if (fallbackToDefaultTenant) {
                throw new FlowableObjectNotFoundException(
                        "Case definition was not found by key '" + caseDefinitionKey + "'. Fallback to default tenant was also used.");
            } else {
                throw new FlowableObjectNotFoundException(
                        "Case definition was not found by key '" + caseDefinitionKey + "' and tenant '" + tenantId + "'");
            }
        }

        return caseDefinition;
    }

    protected CaseDefinition getCaseDefinition(CaseInstanceBuilder caseInstanceBuilder, CommandContext commandContext) {
        CaseDefinition caseDefinition = null;
        if (caseInstanceBuilder.getCaseDefinitionId() != null) {
            String caseDefinitionId = caseInstanceBuilder.getCaseDefinitionId();
            CmmnDeploymentManager deploymentManager = cmmnEngineConfiguration.getDeploymentManager();
            caseDefinition = deploymentManager.findDeployedCaseDefinitionById(caseDefinitionId);

        } else if (caseInstanceBuilder.getCaseDefinitionKey() != null) {

View on GitHub (pinned to d6d39ce1c6)

Solutions

1. Deploy the case definition to the requested tenant (or to the default tenant) so the key resolves
2. Query CaseDefinitionQuery with tenantId to see which tenants actually have the key
3. Verify the key spelling and that fallbackToDefaultTenant semantics match your expectation
4. Check the deployment's tenant id (CmmnRepositoryService) versus the value you pass

Example fix

// before
cmmnRuntimeService.createCaseInstanceBuilder()
    .caseDefinitionKey("orderCase").tenantId("acme").fallbackToDefaultTenant().start(); // missing everywhere
// after
cmmnRepositoryService.createDeployment().addClasspathResource("orderCase.cmmn.xml")
    .tenantId("acme").deploy();
cmmnRuntimeService.createCaseInstanceBuilder()
    .caseDefinitionKey("orderCase").tenantId("acme").start();

boolean existsForTenant = cmmnRepositoryService.createCaseDefinitionQuery()
    .caseDefinitionKey(key).tenantId(tenantId).count() > 0;
boolean existsDefault = cmmnRepositoryService.createCaseDefinitionQuery()
    .caseDefinitionKey(key).tenantId("default-or-empty").count() > 0;
if (!existsForTenant && !(existsDefault && fallback)) throw new IllegalStateException("Key not deployed for tenant " + tenantId);

try {
    cmmnRuntimeService.createCaseInstanceBuilder()
        .caseDefinitionKey(key).tenantId(tenantId).fallbackToDefaultTenant().start();
} catch (FlowableObjectNotFoundException e) {
    // deploy to the tenant or default tenant, then retry
}

When it happens

Trigger: Starting/resolving a case by caseDefinitionKey with a non-null tenantId and fallbackToDefaultTenant=true, where neither the tenant's definition nor the default-tenant definition exists for that key.

Common situations: Definition deployed only to a tenant different from the requested one and not present under the default tenant either; key typo; deployment never performed in this database.

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

• Case definition was not found by key '<caseDefinitionKey>' a
• No case definition found for key '${caseDefinitionKey}'. Fal
• Case definition with key '${caseDefinitionKey}' and tenantId
• Cannot find case definition with id
• Cannot find case definition for id:

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