flowable/flowable-engine · error · FlowableIllegalArgumentException

${aonfe.getMessage()}

Error message

${aonfe.getMessage()}

What it means

In CaseInstanceCollectionResource.createCaseInstance, a FlowableObjectNotFoundException raised while starting a case instance (e.g. unknown case definition key or missing definition) is re-wrapped as a FlowableIllegalArgumentException carrying the original message. It signals that the REST request referenced an object that does not exist in the CMMN engine.

Source

Thrown at modules/flowable-cmmn-rest/src/main/java/org/flowable/cmmn/rest/service/api/runtime/caze/CaseInstanceCollectionResource.java:442

            CaseInstanceResponse caseInstanceResponse = null;
            if (request.getReturnVariables()) {
                Map<String, Object> runtimeVariableMap = runtimeService.getVariables(instance.getId());
                caseInstanceResponse = restResponseFactory.createCaseInstanceResponse(instance, true, runtimeVariableMap);

            } else {
                caseInstanceResponse = restResponseFactory.createCaseInstanceResponse(instance);
            }
            
            CaseDefinition caseDefinition = repositoryService.createCaseDefinitionQuery().caseDefinitionId(caseInstanceResponse.getCaseDefinitionId()).singleResult();
            if (caseDefinition != null) {
                caseInstanceResponse.setCaseDefinitionName(caseDefinition.getName());
                caseInstanceResponse.setCaseDefinitionDescription(caseDefinition.getDescription());
            }

            return caseInstanceResponse;

        } catch (FlowableObjectNotFoundException aonfe) {
            throw new FlowableIllegalArgumentException(aonfe.getMessage(), aonfe);
        }
    }

    @ApiOperation(value = "Post action request to delete/terminate a bulk of case instances", tags = { "Case Instances" }, nickname = "bulkDeleteCaseInstances", code = 204)
    @ApiResponses(value = {
            @ApiResponse(code = 204, message = "Indicates the bulk of case instances was found and deleted. Response body is left empty intentionally."),
            @ApiResponse(code = 404, message = "Indicates at least one requested case instance was not found.")
    })
    @PostMapping(value = "/cmmn-runtime/case-instances/delete")
    @ResponseStatus(value = HttpStatus.NO_CONTENT)
    public void bulkDeleteCaseInstances(@RequestBody BulkDeleteInstancesRestActionRequest request) {
        if (BulkDeleteInstancesRestActionRequest.DELETE_ACTION.equals(request.getAction())) {
            if (restApiInterceptor != null) {
                restApiInterceptor.bulkDeleteCaseInstances(request.getInstanceIds());
            }
            runtimeService.bulkDeleteCaseInstances(request.getInstanceIds());
        } else if (BulkDeleteInstancesRestActionRequest.TERMINATE_ACTION.equals(request.getAction())) {
            if (restApiInterceptor != null) {

View on GitHub (pinned to d6d39ce1c6)

Solutions

1. Verify the case definition key/id exists via GET /cmmn-repository/case-definitions before starting the instance.
2. Ensure the CMMN deployment containing the definition is present in the target database/tenant.
3. Catch FlowableIllegalArgumentException and surface a 404-style message pointing at the definition reference.
4. Fix typos or stale configuration referencing the old definition key.

Example fix

// before
POST /cmmn-runtime/case-instances {"caseDefinitionKey": "orderProces"}
// after
POST /cmmn-runtime/case-instances {"caseDefinitionKey": "orderProcess"} // key verified against case-definitions endpoint

// Java: check definition exists before starting
CaseDefinition def = repositoryService.createCaseDefinitionQuery()
    .caseDefinitionKey(key).latestVersion().singleResult();
if (def == null) throw new IllegalArgumentException("Unknown case definition key: " + key);

try { caseInstance = runtimeService.startCaseInstance(request); }
catch (FlowableIllegalArgumentException e) { /* 404-style response, e.getCause() is FlowableObjectNotFoundException */ }

When it happens

Trigger: POST to the case instances collection URL with a caseDefinitionId/caseDefinitionKey that does not exist, or referencing a definition not deployed to the runtime repository, causing FlowableObjectNotFoundException which is converted to FlowableIllegalArgumentException.

Common situations: Typo in case definition key; case definition deployed to a different tenant; definition deleted or undeployed before the call; environment mismatch (test vs prod repository).

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

• Could not find a case instance with id '${caseInstanceId}'.
• Could not find a case instance
• Case instance '${instanceId}' doesn't have a variable with n
• Could not find a variable with name '${variableName}'.
• No case instance found for id ${caseInstanceEntityId}

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