{"record":{"id":"a9c71af74002e10d","repo":"flowable/flowable-engine","slug":"error-while-starting-process-using-startprocess-o","errorCode":null,"errorMessage":"Error while starting process using @StartProcess on method  '': ","messagePattern":"Error while starting process using @StartProcess on method  '': ","errorType":"exception","errorClass":"FlowableException","httpStatus":null,"severity":"error","filePath":"modules/flowable-cdi/src/main/java/org/flowable/cdi/impl/annotation/StartProcessInterceptor.java","lineNumber":72,"sourceCode":"\r\n            Map<String, Object> variables = extractVariables(startProcessAnnotation, ctx);\r\n\r\n            if (name.length() > 0) {\r\n                businessProcess.startProcessByName(name, variables);\r\n            } else {\r\n                businessProcess.startProcessByKey(key, variables);\r\n            }\r\n\r\n            return result;\r\n        } catch (InvocationTargetException e) {\r\n            Throwable cause = e.getCause();\r\n            if (cause instanceof Exception) {\r\n                throw (Exception) cause;\r\n            } else {\r\n                throw e;\r\n            }\r\n        } catch (Exception e) {\r\n            throw new FlowableException(\"Error while starting process using @StartProcess on method  '\" + ctx.getMethod() + \"': \" + e.getMessage(), e);\r\n        }\r\n    }\r\n\r\n    private Map<String, Object> extractVariables(StartProcess startProcessAnnotation, InvocationContext ctx) throws Exception {\r\n        Map<String, Object> variables = new HashMap<>();\r\n        for (Field field : ctx.getMethod().getDeclaringClass().getDeclaredFields()) {\r\n            if (!field.isAnnotationPresent(ProcessVariable.class)) {\r\n                continue;\r\n            }\r\n            field.setAccessible(true);\r\n            ProcessVariable processStartVariable = field.getAnnotation(ProcessVariable.class);\r\n            String fieldName = processStartVariable.value();\r\n            if (fieldName == null || fieldName.length() == 0) {\r\n                fieldName = field.getName();\r\n            }\r\n            Object value = field.get(ctx.getTarget());\r\n            variables.put(fieldName, value);\r\n        }\r","sourceCodeStart":54,"sourceCodeEnd":90,"githubUrl":"https://github.com/flowable/flowable-engine/blob/d6d39ce1c69ff244f2d9dc6af756a9b95e865586/modules/flowable-cdi/src/main/java/org/flowable/cdi/impl/annotation/StartProcessInterceptor.java#L54-L90","documentation":"StartProcessInterceptor wraps methods annotated with @StartProcess; after the method returns it starts a process instance, extracting variables from annotated fields/parameters. Any exception raised during start (or during variable extraction) is rethrown as FlowableException with the message 'Error while starting process using @StartProcess on method <method>: <cause message>'.","triggerScenarios":"Invoking a @StartProcess-annotated method when: the process definition key does not match any deployed definition, variable extraction (annotated fields) fails reflectively, or the engine throws (e.g. validation, missing deployment). The intercepted method name appears in the message.","commonSituations":"Process definition not deployed or key typo'd after renaming the BPMN file; annotated business method with wrong @ProcessVariable-style field annotations; running outside an active engine/CDI setup so the runtime service can't start the instance.","solutions":["Read the wrapped cause (getCause()) for the real engine error; the outer message only names the method.","Verify the process definition key matches a deployed definition: repositoryService.createProcessDefinitionQuery().processDefinitionKey(key).latestVersion().singleResult() != null.","Check @StartProcess annotation attributes (key, viaBusinessProcess) and the annotated fields used for variable extraction."],"exampleFix":"// before\n@StartProcess(key = \"orderProces\")\npublic void submit() { ... }\n// after\n@StartProcess(key = \"orderProcess\") // key must match bpmn process id\npublic void submit() { ... }","handlingStrategy":"try-catch","validationCode":"boolean deployed = repositoryService.createProcessDefinitionQuery()\n    .processDefinitionKey(processKey).latestVersion().count() > 0;","typeGuard":"null","tryCatchPattern":"try { startProcessMethod(); } catch (FlowableException e) { log.error(\"start failed: {}\", e.getCause() != null ? e.getCause().getMessage() : e.getMessage(), e); }","preventionTips":["Verify the @StartProcess key matches a deployed process definition id","Ensure BPMN resources are deployed before application use","Check annotated fields/parameter annotations used for variable extraction"],"tags":["cdi","process-start","wrapper-exception"],"backgroundTag":"invalid-config-value","analyzedSha":"d6d39ce1c69ff244f2d9dc6af756a9b95e865586","analyzedAt":"2026-09-11T06:41:19.413Z","contentChangedAt":"2026-09-11T06:41:19.413Z","schemaVersion":2},"datasetVersion":"2026-09-18T11:17:12.947Z"}