flowable/flowable-engine · error · FlowableException

Could not start process instance with business key ${key}

Error message

Could not start process instance with business key ${key}

What it means

FlowableProducer.findProcessInstanceId resolves the process instance id for an exchange by querying Flowable with the business key taken from the PROCESS_KEY_PROPERTY exchange property. If no process instance exists with that business key, Flowable throws this FlowableException because the exchange assumed a process was already started under that key.

Source

Thrown at modules/flowable-camel/src/main/java/org/flowable/camel/FlowableProducer.java:164

        if (execution == null) {
            throw new FlowableException("Could not find activity " + activity + " for processId " + processInstanceId +
                    " in defined timeout of " + timeout + " ms.");
        }

        runtimeService.setVariables(execution.getId(), ExchangeUtils.prepareVariables(exchange, getFlowableEndpoint()));
        runtimeService.trigger(execution.getId());
    }

    protected String findProcessInstanceId(Exchange exchange) {
        String processInstanceId = exchange.getProperty(PROCESS_ID_PROPERTY, String.class);
        if (processInstanceId != null) {
            return processInstanceId;
        }
        String key = exchange.getProperty(PROCESS_KEY_PROPERTY, String.class);
        ProcessInstance processInstance = runtimeService.createProcessInstanceQuery().processInstanceBusinessKey(key).singleResult();

        if (processInstance == null) {
            throw new FlowableException("Could not start process instance with business key " + key);
        }
        return processInstance.getId();
    }

    protected ProcessInstance startProcess(Exchange exchange) {
        FlowableEndpoint endpoint = getFlowableEndpoint();
        String key = exchange.getProperty(PROCESS_KEY_PROPERTY, String.class);
        try {
            if (endpoint.isSetProcessInitiator()) {
                setProcessInitiator(ExchangeUtils.prepareInitiator(exchange, endpoint));
            }

            if (key == null) {
                return runtimeService.startProcessInstanceByKey(processKey, ExchangeUtils.prepareVariables(exchange, endpoint));
            } else {
                return runtimeService.startProcessInstanceByKey(processKey, key, ExchangeUtils.prepareVariables(exchange, endpoint));
            }

View on GitHub (pinned to d6d39ce1c6)

Solutions

  1. Ensure the process instance was actually started (with that business key) before sending subsequent exchanges correlated by the key.
  2. Verify the exchange property FlowableConstants.PROCESS_KEY_PROPERTY is set to the same value used at startProcess.
  3. Check the process has not already completed; query history (historicProcessInstanceQuery) to confirm its lifecycle.
  4. Alternatively pass the processInstanceId directly via the PROCESS_INSTANCE_ID_PROPERTY to skip business-key lookup.

Example fix

// before
exchange.setProperty(ExchangeUtils.PROCESS_KEY_PROPERTY, "order-42"); // never started
// after
exchange.setProperty(ExchangeUtils.PROCESS_KEY_PROPERTY, "order-42");
runtimeService.startProcessInstanceByKey("myProcess", "order-42"); // then correlate
Defensive patterns

Strategy: validation

Validate before calling

String key = exchange.getProperty(ExchangeUtils.PROCESS_KEY_PROPERTY, String.class);
if (key == null || runtimeService.createProcessInstanceQuery()
        .processInstanceBusinessKey(key).singleResult() == null) {
    throw new IllegalStateException("No running process instance for business key " + key);
}

Try / catch

try {
    producer.process(exchange);
} catch (FlowableException e) {
    if (e.getMessage().startsWith("Could not start process instance with business key")) {
        // start the process first, or fall back to startProcess
    }
    throw e;
}

Prevention

When it happens

Trigger: Using the exchange-correlation mode (no explicit process instance id) where process() looks up the instance via processInstanceBusinessKey(key), but the process instance with that business key was never started, already completed, or the property value is wrong.

Common situations: Sending a follow-up exchange to a flowable endpoint before the initial one started the process; process already finished (history only, not runtime query); business key mutated or generated differently between calls; camelContext mismatch so the key property is absent/null.

Understand the failure class

Background: Record Not Found Errors: "not found", RecordNotFound, and "was not found" — what they mean and how to fix them — this error's family across 28 libraries.

Related errors

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