{"record":{"id":"1edd5f7edceda97a","repo":"flowable/flowable-engine","slug":"cause","errorCode":null,"errorMessage":"${cause}","messagePattern":"\\$\\{cause\\}","errorType":"exception","errorClass":"FlowableIllegalArgumentException","httpStatus":400,"severity":"error","filePath":"modules/flowable-rest/src/main/java/org/flowable/rest/service/api/runtime/process/ProcessInstanceCollectionResource.java","lineNumber":450,"sourceCode":"                    runtimeVariableMap = runtimeService.getVariables(instance.getId());\n                }\n                processInstanceResponse = restResponseFactory.createProcessInstanceResponse(instance, true, runtimeVariableMap, historicVariableList);\n\n            } else {\n                processInstanceResponse = restResponseFactory.createProcessInstanceResponse(instance);\n            }\n            \n            ProcessDefinition processDefinition = repositoryService.createProcessDefinitionQuery().processDefinitionId(processInstanceResponse.getProcessDefinitionId()).singleResult();\n            \n            if (processDefinition != null) {\n                processInstanceResponse.setProcessDefinitionName(processDefinition.getName());\n                processInstanceResponse.setProcessDefinitionDescription(processDefinition.getDescription());\n            }\n\n            return processInstanceResponse;\n\n        } catch (FlowableObjectNotFoundException e) {\n            throw new FlowableIllegalArgumentException(e.getMessage(), e);\n        }\n    }\n\n    @ApiOperation(value = \"Bulk delete process instances\", tags = { \"Process Instances\" }, nickname = \"deleteProcessInstances\", code = 204)\n    @ApiResponses(value = {\n            @ApiResponse(code = 204, message = \"Indicates the bulk of process instances was found and deleted. Response body is left empty intentionally.\"),\n            @ApiResponse(code = 404, message = \"Indicates at least one requested process instance was not found.\")\n    })\n    @PostMapping(value = \"/runtime/process-instances/delete\")\n    @ResponseStatus(value = HttpStatus.NO_CONTENT)\n    public void bulkDeleteProcessInstances(@RequestBody BulkDeleteInstancesRestActionRequest request) {\n        if (BulkDeleteInstancesRestActionRequest.DELETE_ACTION.equals(request.getAction())) {\n\n            if (restApiInterceptor != null) {\n                restApiInterceptor.bulkDeleteProcessInstances(request.getInstanceIds());\n            }\n            runtimeService.bulkDeleteProcessInstances(request.getInstanceIds(), request.getDeleteReason());\n        } else {","sourceCodeStart":432,"sourceCodeEnd":468,"githubUrl":"https://github.com/flowable/flowable-engine/blob/d6d39ce1c69ff244f2d9dc6af756a9b95e865586/modules/flowable-rest/src/main/java/org/flowable/rest/service/api/runtime/process/ProcessInstanceCollectionResource.java#L432-L468","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Verify the processDefinitionKey/Id exists: GET /repository/process-definitions and confirm the key (and tenantId) matches.","Include the correct tenantId in the request if you deploy per-tenant (e.g. processDefinitionKey + \"@tenantId\" style resolution rules).","Ensure your app actually deployed the BPMN before starting instances (check ACT_RE_PROCDEF / deployment logs)."],"exampleFix":"// before\nPOST {\"processDefinitionKey\":\"orderProces\"}\n// after\nPOST {\"processDefinitionKey\":\"orderProcess\",\"tenantId\":\"acme\"} // key confirmed via GET /repository/process-definitions","handlingStrategy":"validation","validationCode":"// before starting, confirm the definition exists\nList<Map<String, Object>> defs = restClient.get(\"/repository/process-definitions?key=\" + key + \"&latest=true\");\nif (defs.isEmpty()) {\n    throw new IllegalStateException(\"No deployed process definition for key: \" + key);\n}","typeGuard":null,"tryCatchPattern":"try {\n    restClient.startProcessInstance(req);\n} catch (HttpClientErrorException.NotFound | HttpClientErrorException.BadRequest e) {\n    if (e.getResponseBodyAsString().contains(processKey)) {\n        // deploy or correct key/tenant before retrying\n    }\n}","preventionTips":["Look up definition keys from /repository/process-definitions rather than hard-coding strings.","Deploy BPMN as part of the release pipeline before smoke tests start instances.","Always send tenantId when running multi-tenant."],"tags":["rest-api","process-instance","resource-not-found","java"],"backgroundTag":"resource-not-found","analyzedSha":"d6d39ce1c69ff244f2d9dc6af756a9b95e865586","analyzedAt":"2026-09-11T06:41:19.413Z","contentChangedAt":"2026-09-11T06:41:19.413Z","schemaVersion":2},"datasetVersion":"2026-09-14T16:17:12.679Z"}