flowable/flowable-engine · error · ActivitiActivityExecutionException

couldn't execute activity <

Error message

couldn't execute activity <${type} id="${activityId}" ...>: 

What it means

This error wraps any Throwable thrown by an activity's Behavior.execute() during process execution in the Flowable/Activiti PVM. The engine re-wraps non-Activiti exceptions into an ActivitiActivityExecutionException prefixed with the activity type and id so the failing process node can be identified. The original cause is preserved as the exception cause.

Solutions

1. Read the cause chain of the ActivitiActivityExecutionException to find the real exception from the behavior code
2. Check the activity id/type in the message and inspect that node's behavior/delegate implementation
3. Fix or guard the failing code in the ActivityBehavior.execute() implementation
4. Add process variables null-checks inside the delegate before use

Example fix

// before
public void execute(DelegateExecution exec) {
  String url = (String) exec.getVariable("url");
  http.get(url); // NPE if variable missing
}
// after
public void execute(DelegateExecution exec) {
  String url = (String) exec.getVariable("url");
  if (url == null) throw new ActivitiException("url variable required");
  http.get(url);
}

// before starting the process instance
if (processVariables.get("url") == null) {
  throw new IllegalArgumentException("required process variable 'url' is missing");
}

// Java: check delegate field before use
if (!(execution.getVariable("count") instanceof Integer)) {
  throw new ActivitiException("'count' must be an Integer");
}

try {
  runtimeService.startProcessInstanceByKey(key, vars);
} catch (ActivitiActivityExecutionException e) {
  log.error("activity {} failed", e.getActivityId(), e.getCause()); // inspect cause
}

When it happens

Trigger: Any RuntimeException or checked Throwable thrown from inside a custom ActivityBehavior's execute(execution) method while the PVM atomic operation ACTIVITY_EXECUTE runs the node (e.g. a delegate throwing NPE, a service task delegate class failing, a checked exception from business logic).

Common situations: Custom JavaDelegate or ActivityBehavior code throwing NPE due to missing process variables; misconfigured service-task class names causing instantiation failures; database/network calls inside delegates failing; switching Activiti versions where a behavior API changed.

Understand the failure class

Background: "This is a bug, please report it": internal invariant violations, unreachable panics, and SNH errors explained — this error's family across 47 libraries.

Related errors

• couldn't execute event listener :
• couldn't process signal
• Error while completing sub process of execution
• already taking a transition
• ' didn't resolve to a Collection

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

Appendix: source

Thrown at modules/flowable5-engine/src/main/java/org/activiti/engine/impl/pvm/runtime/AtomicOperationActivityExecute.java:71

                Context.getProcessEngineConfiguration().getEventDispatcher().dispatchEvent(
                        ActivitiEventBuilder.createActivityEvent(FlowableEngineEventType.ACTIVITY_STARTED,
                                execution.getActivity().getId(),
                                (String) execution.getActivity().getProperty("name"),
                                execution.getId(),
                                execution.getProcessInstanceId(),
                                execution.getProcessDefinitionId(),
                                (String) activity.getProperties().get("type"),
                                activity.getActivityBehavior().getClass().getCanonicalName()),
                        EngineConfigurationConstants.KEY_PROCESS_ENGINE_CONFIG);
            }

            activityBehavior.execute(execution);

        } catch (ActivitiException e) {
            throw e;
        } catch (Throwable t) {
            LogMDC.putMDCExecution(execution);
            throw new ActivitiActivityExecutionException("couldn't execute activity <" + activity.getProperty("type") + " id=\"" + activity.getId() + "\" ...>: " + t.getMessage(), t);
        }
    }
}

View on GitHub (pinned to d6d39ce1c6)