flowable/flowable-engine · error · FlowableException

invalid command interceptor chain configuration:

Error message

invalid command interceptor chain configuration: 

What it means

The command interceptor chain is the pipeline of CommandInterceptor objects that wraps every engine command. initInterceptorChain requires a non-null, non-empty list to link the interceptors; otherwise the CommandExecutor would have no chain head, so this FlowableException is thrown.

Solutions

1. Ensure the command interceptor chain contains at least one interceptor (ending with CommandInvoker)
2. Check overrides of initCommandInterceptors/initInterceptorChain for logic that can return an empty list
3. Restore the default interceptor configuration or append your interceptor to the existing chain instead of replacing it

Example fix

// before
config.setCommandInterceptors(Collections.emptyList());
// after
List<CommandInterceptor> interceptors = new ArrayList<>();
interceptors.add(new LogInterceptor());
interceptors.add(new CommandInvoker());
config.setCommandInterceptors(interceptors);

List<CommandInterceptor> chain = config.getCommandInterceptors(); if (chain == null || chain.isEmpty()) { throw new IllegalStateException("command interceptor chain must not be empty"); }

When it happens

Trigger: Calling initInterceptorChain(chain) (directly or via initCommandInterceptors/customizations) with a null or empty interceptor list, typically from a custom config that overrides initInterceptorChain or clears commandInterceptors.

Common situations: Custom engine configuration removing/replacing the default interceptor chain without adding any interceptors; subclass overriding initCommandInterceptors and forgetting to populate the list.

Understand the failure class

Background: "must not be empty", "cannot be empty" — required-field validation errors across open-source libraries — this error's family across 41 libraries.

Related errors

• A channel key detection value is required for the channel…
• A datasource is required for initializing the engine
• Builder is missing constructor (can't pass features)
• Cannot migrate process(es), not enough information
• Cannot parse EL property

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

Appendix: source

Thrown at modules/flowable-engine-common/src/main/java/org/flowable/common/engine/impl/AbstractEngineConfiguration.java:620

    public abstract String getEngineCfgKey();
    
    public abstract String getEngineScopeType();

    public List<CommandInterceptor> getAdditionalDefaultCommandInterceptors() {
        return null;
    }

    public void initCommandExecutor() {
        if (commandExecutor == null) {
            CommandInterceptor first = initInterceptorChain(commandInterceptors);
            commandExecutor = new CommandExecutorImpl(getDefaultCommandConfig(), first);
        }
    }

    public CommandInterceptor initInterceptorChain(List<CommandInterceptor> chain) {
        if (chain == null || chain.isEmpty()) {
            throw new FlowableException("invalid command interceptor chain configuration: " + chain);
        }
        for (int i = 0; i < chain.size() - 1; i++) {
            chain.get(i).setNext(chain.get(i + 1));
        }
        return chain.get(0);
    }

    public abstract CommandInterceptor createTransactionInterceptor();


    public void initBeans() {
        if (beans == null) {
            beans = new HashMap<>();
        }
    }

    // id generator
    // /////////////////////////////////////////////////////////////

View on GitHub (pinned to d6d39ce1c6)