What causes "${message}" in flowable/flowable-engine?

Read the cause for the missing class name and add the jar containing it to the classpath

flowable/flowable-engine · error · FlowableClassLoadingException

${message}

Error message

${message}

What it means

An Activiti 5 ActivitiClassLoadingException raised inside compatibility-handled commands is translated to the Flowable equivalent FlowableClassLoadingException, preserving message and cause. It indicates a class needed by the v5-style execution could not be loaded.

Solutions

Read the cause for the missing class name and add the jar containing it to the classpath
Update delegate/listener expressions to the migrated Flowable package names
Redeploy the process definitions with corrected class references

Example fix

// before
<serviceTask flowable:delegateExpression="${com.old.MyDelegate}"/>
// after
<serviceTask flowable:delegateExpression="${com.new.MyDelegate}"/>

Defensive patterns

Strategy: try-catch

Validate before calling

String cls = delegateExpressionClassName;
try { Class.forName(cls); } catch (ClassNotFoundException e) { throw new IllegalStateException("Missing class on classpath: " + cls); }

Try / catch

try {
    handler.executeJob(job);
} catch (FlowableClassLoadingException e) {
    log.error("Cannot load {}: check deployment classpath", e.getCause());
    throw e;
}

Prevention

Replicate all Activiti 5 delegate classes into the Flowable application classpath
Migrate org.activiti.* imports to org.flowable.* before redeploying definitions
Smoke-test migrated definitions in a staging environment with an identical classpath

When it happens

Trigger: Any compatibility-handler operation whose underlying v5 code fails to load a class (delegate class, listener, custom type) — e.g., the delegateExpression points to a class absent from the classpath.

Common situations: Deployed v5 process definitions referencing old package names (org.activiti.*) after migration; missing jars in the Flowable deployment; fat-jar classpath differences between environments.

Related errors

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

Appendix: source

Thrown at modules/flowable5-compatibility/src/main/java/org/flowable/compatibility/DefaultFlowable5CompatibilityHandler.java:1165

        activity5Job.setJobHandlerType(job.getJobHandlerType());
        activity5Job.setEndDate(job.getEndDate());
        activity5Job.setRepeat(job.getRepeat());
        activity5Job.setProcessDefinitionId(job.getProcessDefinitionId());
        activity5Job.setProcessInstanceId(job.getProcessInstanceId());
        activity5Job.setRetries(job.getRetries());
        activity5Job.setRevision(job.getRevision());
        activity5Job.setTenantId(job.getTenantId());
        activity5Job.setExceptionMessage(job.getExceptionMessage());
        return activity5Job;
    }

    protected void handleActivitiException(org.activiti.engine.ActivitiException e) {
        if (e instanceof org.activiti.engine.delegate.BpmnError) {
            org.activiti.engine.delegate.BpmnError activiti5BpmnError = (org.activiti.engine.delegate.BpmnError) e;
            throw new BpmnError(activiti5BpmnError.getErrorCode(), activiti5BpmnError.getMessage());

        } else if (e instanceof org.activiti.engine.ActivitiClassLoadingException) {
            throw new FlowableClassLoadingException(e.getMessage(), e.getCause());

        } else if (e instanceof org.activiti.engine.ActivitiObjectNotFoundException) {
            org.activiti.engine.ActivitiObjectNotFoundException activiti5ObjectNotFoundException = (org.activiti.engine.ActivitiObjectNotFoundException) e;
            throw new FlowableObjectNotFoundException(activiti5ObjectNotFoundException.getMessage(),
                    activiti5ObjectNotFoundException.getObjectClass(), activiti5ObjectNotFoundException.getCause());

        } else if (e instanceof org.activiti.engine.ActivitiOptimisticLockingException) {
            throw new FlowableOptimisticLockingException(e.getMessage());

        } else if (e instanceof org.activiti.engine.ActivitiIllegalArgumentException) {
            throw new FlowableIllegalArgumentException(e.getMessage(), e.getCause());

        } else {
            if (e.getCause() instanceof org.activiti.engine.delegate.BpmnError) {
                org.activiti.engine.delegate.BpmnError activiti5BpmnError = (org.activiti.engine.delegate.BpmnError) e.getCause();
                throw new BpmnError(activiti5BpmnError.getErrorCode(), activiti5BpmnError.getMessage());
                
            } else if (e.getCause() instanceof org.flowable.engine.delegate.BpmnError) {

View on GitHub (pinned to d6d39ce1c6)