flowable/flowable-engine · error · FlowableObjectNotFoundException

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

Error message

Case definition was not found by key '<caseDefinitionKey>' and tenant '<tenantId>'

What it means

resolveCaseDefinition found no case definition for the key and tenant, and no fallback to the default tenant was requested, so a FlowableObjectNotFoundException including both key and tenant is thrown. This is the strictest of the three not-found branches.

Source

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

                }
            }
        } 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) {
            String caseDefinitionKey = caseInstanceBuilder.getCaseDefinitionKey();
            String tenantId = caseInstanceBuilder.getTenantId();
            String parentDeploymentId = caseInstanceBuilder.getCaseDefinitionParentDeploymentId();

View on GitHub (pinned to d6d39ce1c6)

Solutions

  1. Deploy the case definition with the exact tenantId requested
  2. Enable fallbackToDefaultTenant() on the case instance builder if default-tenant definitions should be used
  3. Query CaseDefinitionQuery().caseDefinitionKey(key).list() to discover which tenant has the key and correct the tenantId
  4. Confirm tenant id spelling/case matches the deployment

Example fix

// before
cmmnRuntimeService.createCaseInstanceBuilder()
    .caseDefinitionKey("orderCase").tenantId("acme").start(); // deployed under default tenant only
// after
cmmnRuntimeService.createCaseInstanceBuilder()
    .caseDefinitionKey("orderCase").tenantId("acme").fallbackToDefaultTenant().start();
// or deploy explicitly to acme
Defensive patterns

Strategy: validation

Validate before calling

long n = cmmnRepositoryService.createCaseDefinitionQuery()
    .caseDefinitionKey(key).tenantId(tenantId).count();
if (n == 0) throw new IllegalStateException("No case definition for key " + key + " and tenant " + tenantId);

Try / catch

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

Prevention

When it happens

Trigger: Starting/resolving a case by caseDefinitionKey with a specific non-null tenantId (not NO_TENANT_ID) and fallbackToDefaultTenant=false, where no case definition is deployed for that key and tenant combination.

Common situations: Multi-tenant setup where the definition was deployed under a different tenant or the default tenant only; tenant id mismatch (case-sensitive) between request and deployment; definition not yet deployed in this environment.

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