flowable/flowable-engine · error · FlowableException

Error while starting process using @StartProcess on method …

Error message

Error while starting process using @StartProcess on method  '': 

What it means

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>'.

Solutions

1. Read the wrapped cause (getCause()) for the real engine error; the outer message only names the method.
2. Verify the process definition key matches a deployed definition: repositoryService.createProcessDefinitionQuery().processDefinitionKey(key).latestVersion().singleResult() != null.
3. Check @StartProcess annotation attributes (key, viaBusinessProcess) and the annotated fields used for variable extraction.

Example fix

// before
@StartProcess(key = "orderProces")
public void submit() { ... }
// after
@StartProcess(key = "orderProcess") // key must match bpmn process id
public void submit() { ... }

boolean deployed = repositoryService.createProcessDefinitionQuery()
    .processDefinitionKey(processKey).latestVersion().count() > 0;

null

try { startProcessMethod(); } catch (FlowableException e) { log.error("start failed: {}", e.getCause() != null ? e.getCause().getMessage() : e.getMessage(), e); }

When it happens

Trigger: 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.

Common situations: 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.

Understand the failure class

Background: "Invalid value" and "allowed values are" config errors: what your library rejected and how to fix it — this error's family across 41 libraries.

Related errors

• Error while completing task:
• Cannot associate , already associated with . Disassociate…
• Cannot associate execution by id: no execution with id '
• Cannot associate with execution: null
• Cannot disassociate execution, no

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

Appendix: source

Thrown at modules/flowable-cdi/src/main/java/org/flowable/cdi/impl/annotation/StartProcessInterceptor.java:72

            Map<String, Object> variables = extractVariables(startProcessAnnotation, ctx);

            if (name.length() > 0) {
                businessProcess.startProcessByName(name, variables);
            } else {
                businessProcess.startProcessByKey(key, variables);
            }

            return result;
        } catch (InvocationTargetException e) {
            Throwable cause = e.getCause();
            if (cause instanceof Exception) {
                throw (Exception) cause;
            } else {
                throw e;
            }
        } catch (Exception e) {
            throw new FlowableException("Error while starting process using @StartProcess on method  '" + ctx.getMethod() + "': " + e.getMessage(), e);
        }
    }

    private Map<String, Object> extractVariables(StartProcess startProcessAnnotation, InvocationContext ctx) throws Exception {
        Map<String, Object> variables = new HashMap<>();
        for (Field field : ctx.getMethod().getDeclaringClass().getDeclaredFields()) {
            if (!field.isAnnotationPresent(ProcessVariable.class)) {
                continue;
            }
            field.setAccessible(true);
            ProcessVariable processStartVariable = field.getAnnotation(ProcessVariable.class);
            String fieldName = processStartVariable.value();
            if (fieldName == null || fieldName.length() == 0) {
                fieldName = field.getName();
            }
            Object value = field.get(ctx.getTarget());
            variables.put(fieldName, value);
        }

View on GitHub (pinned to d6d39ce1c6)