flowable/flowable-engine · error · FlowableIllegalArgumentException

${cause}

Error message

${cause}

What it means

When the process start fails because the referenced process definition or process instance does not exist, Flowable's REST layer catches FlowableObjectNotFoundException and rethrows it as FlowableIllegalArgumentException carrying the original message (the ${cause} placeholder). The client therefore sees the 'not found' text wrapped as an illegal-argument error with HTTP 400 instead of 404.

Source

Thrown at modules/flowable-rest/src/main/java/org/flowable/rest/service/api/runtime/process/ProcessInstanceCollectionResource.java:450

                    runtimeVariableMap = runtimeService.getVariables(instance.getId());
                }
                processInstanceResponse = restResponseFactory.createProcessInstanceResponse(instance, true, runtimeVariableMap, historicVariableList);

            } else {
                processInstanceResponse = restResponseFactory.createProcessInstanceResponse(instance);
            }
            
            ProcessDefinition processDefinition = repositoryService.createProcessDefinitionQuery().processDefinitionId(processInstanceResponse.getProcessDefinitionId()).singleResult();
            
            if (processDefinition != null) {
                processInstanceResponse.setProcessDefinitionName(processDefinition.getName());
                processInstanceResponse.setProcessDefinitionDescription(processDefinition.getDescription());
            }

            return processInstanceResponse;

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

    @ApiOperation(value = "Bulk delete process instances", tags = { "Process Instances" }, nickname = "deleteProcessInstances", code = 204)
    @ApiResponses(value = {
            @ApiResponse(code = 204, message = "Indicates the bulk of process instances was found and deleted. Response body is left empty intentionally."),
            @ApiResponse(code = 404, message = "Indicates at least one requested process instance was not found.")
    })
    @PostMapping(value = "/runtime/process-instances/delete")
    @ResponseStatus(value = HttpStatus.NO_CONTENT)
    public void bulkDeleteProcessInstances(@RequestBody BulkDeleteInstancesRestActionRequest request) {
        if (BulkDeleteInstancesRestActionRequest.DELETE_ACTION.equals(request.getAction())) {

            if (restApiInterceptor != null) {
                restApiInterceptor.bulkDeleteProcessInstances(request.getInstanceIds());
            }
            runtimeService.bulkDeleteProcessInstances(request.getInstanceIds(), request.getDeleteReason());
        } else {

View on GitHub (pinned to d6d39ce1c6)

Solutions

1. Verify the processDefinitionKey/Id exists: GET /repository/process-definitions and confirm the key (and tenantId) matches.
2. Include the correct tenantId in the request if you deploy per-tenant (e.g. processDefinitionKey + "@tenantId" style resolution rules).
3. Ensure your app actually deployed the BPMN before starting instances (check ACT_RE_PROCDEF / deployment logs).

Example fix

// before
POST {"processDefinitionKey":"orderProces"}
// after
POST {"processDefinitionKey":"orderProcess","tenantId":"acme"} // key confirmed via GET /repository/process-definitions

// before starting, confirm the definition exists
List<Map<String, Object>> defs = restClient.get("/repository/process-definitions?key=" + key + "&latest=true");
if (defs.isEmpty()) {
    throw new IllegalStateException("No deployed process definition for key: " + key);
}

try {
    restClient.startProcessInstance(req);
} catch (HttpClientErrorException.NotFound | HttpClientErrorException.BadRequest e) {
    if (e.getResponseBodyAsString().contains(processKey)) {
        // deploy or correct key/tenant before retrying
    }
}

When it happens

Trigger: POST /runtime/process-instances with a processDefinitionKey/processDefinitionId that no deployed definition matches, or a message-start referenced via a non-existent definition; e.g. {"processDefinitionKey":"nonExistentKey"}. Thrown at ProcessInstanceCollectionResource.java:450 in the catch of createProcessInstance.

Common situations: Typos in the process definition key; deploying to a different tenant than the one the REST call targets; definition undeployed or redeployed with a new key/version between test and production; wrong Flowable REST base URL pointing at another 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

• Cannot find plan item with definition id '<planItemDefinitio
• The variable does not have a binary data stream.
• Could not find a job with id ''.
• Could not find a history job with id ''.
• Could not find a dead letter job(s) with id(s) {}

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