flowable/flowable-engine · error · FlowableException

ProcessEngineConfiguration is required

Error message

ProcessEngineConfiguration is required

What it means

ProcessEngineConfigurator.buildEngine() refuses to build a process engine when its `processEngineConfiguration` field is null. Flowable's configurator infra calls buildEngine() after configuring, and the engine cannot be constructed without a ProcessEngineConfiguration. This guards against a configurator that was registered but never given its configuration.

Source

Thrown at modules/flowable-engine-configurator/src/main/java/org/flowable/engine/configurator/ProcessEngineConfigurator.java:119

                dbSqlSessionFactory.getDeletionOrder().add(clazz);
            }
        }
    }

    @Override
    protected List<Class<? extends Entity>> getEntityInsertionOrder() {
        return EntityDependencyOrder.INSERT_ORDER;
    }

    @Override
    protected List<Class<? extends Entity>> getEntityDeletionOrder() {
        return EntityDependencyOrder.DELETE_ORDER;
    }

    @Override
    protected ProcessEngine buildEngine() {
        if (processEngineConfiguration == null) {
            throw new FlowableException("ProcessEngineConfiguration is required");
        }

        return processEngineConfiguration.buildProcessEngine();
    }

    public ProcessEngineConfiguration getProcessEngineConfiguration() {
        return processEngineConfiguration;
    }

    public ProcessEngineConfigurator setProcessEngineConfiguration(ProcessEngineConfiguration processEngineConfiguration) {
        this.processEngineConfiguration = processEngineConfiguration;
        return this;
    }

    protected JobServiceConfiguration getJobServiceConfiguration(AbstractEngineConfiguration engineConfiguration) {
        if (engineConfiguration.getServiceConfigurations().containsKey(EngineConfigurationConstants.KEY_JOB_SERVICE_CONFIG)) {
            return (JobServiceConfiguration) engineConfiguration.getServiceConfigurations().get(EngineConfigurationConstants.KEY_JOB_SERVICE_CONFIG);
        }

View on GitHub (pinned to d6d39ce1c6)

Solutions

1. Call setProcessEngineConfiguration(config) on the configurator before engine build
2. Instead of manual construction, let the owning engine configuration create/attach the configurator (e.g. via its dedicated configurer property such as processEngineConfiguration or the module's own configurator setter)
3. If copying configurators, ensure the configuration reference is transferred too

Example fix

// before
ProcessEngineConfigurator configurator = new ProcessEngineConfigurator();
config.addConfigurator(configurator);

// after
ProcessEngineConfigurator configurator = new ProcessEngineConfigurator();
configurator.setProcessEngineConfiguration(config);
config.addConfigurator(configurator);

if (configurator.getProcessEngineConfiguration() == null) {
    configurator.setProcessEngineConfiguration(engineConfig);
}
engineConfig.addConfigurator(configurator);

When it happens

Trigger: A ProcessEngineConfigurator instance is created and registered with an engine configuration (e.g. via setConfigurators/addConfigurator), but setProcessEngineConfiguration(...) was never called on it before the engine lifecycle invokes buildEngine().

Common situations: Manually instantiating a configurator and adding it to a configuration without wiring the configuration back into it; custom engine bootstrap code that copies configurators between configurations; Spring wiring that forgot the configuration property.

Understand the failure class

Background: "X is required", "must be set", "cannot be empty": the missing-required-config error family, from Vertex AI project/location to WeChat keys — this error's family across 18 libraries.

Related errors

• no org.flowable.app.engine.AppEngine defined in the applicat
• transactionManager is required property for SpringAppEngineC
• Could not find an implementation of the org.flowable.cdi.spi
• DMN repository service is not available
• CommandInvoker must be the last interceptor in the chain

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