flowable/flowable-engine · error · FlowableException

Invalid 'engine' for

Error message

Invalid 'engine' for ${entityType} with id ${id} : ${tag}

What it means

isV5Entity distinguishes engine versions via a tag: a version-5 tag means v5, and null means Flowable 6. If the tag is neither of these (some unexpected non-null value), Flowable cannot determine which engine produced the entity and throws this FlowableException. It guards against corrupted or foreign entity metadata.

Solutions

  1. Inspect the tag column for the entity in the database (ACT_RE_PROCDEF / ACT_RE_DEPLOYMENT) and correct or remove the invalid value.
  2. Restore the entity from a valid backup or redeploy the process definition.
  3. Ensure no other tool or engine version writes these tables with foreign tag formats.
  4. If migrating, follow the official migration procedure so tags are converted correctly.

Example fix

// before: manual DB edit left tag 'activiti-legacy'
UPDATE ACT_RE_PROCDEF SET ENGINE_VERSION_ = 'activiti-legacy' WHERE ID_ = '...';

// after: use null for Flowable 6 entities
UPDATE ACT_RE_PROCDEF SET ENGINE_VERSION_ = NULL WHERE ID_ = '...';
Defensive patterns

Strategy: validation

Validate before calling

// validate engine tag before engine calls
String tag = getEngineVersionTagFromDb(id);
if (tag != null && !Flowable5Util.isVersion5Tag(tag)) {
    throw new IllegalStateException("Unknown engine tag '" + tag + "' for entity " + id);
}

Prevention

When it happens

Trigger: isV5Entity (via isFlowable5Deployment / isFlowable5ProcessDefinition) is passed a tag value that is non-null and not recognized as the v5 tag — e.g. a manually edited or corrupted metadata tag in the deployment/definition tables.

Common situations: Database rows hand-edited or written by another tool with an unknown engine tag; upgrades between intermediate versions that used different tag conventions; mixing engine versions on a shared database.

Understand the failure class

Background: "Invalid value" and "allowed values are" config errors: what your library rejected and how to fix it — this error's family across 41 libraries.

Related errors

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

Appendix: source

Thrown at modules/flowable-engine/src/main/java/org/flowable/engine/impl/util/Flowable5Util.java:134

    public static boolean isFlowable5ProcessDefinition(ProcessDefinition processDefinition, ProcessEngineConfigurationImpl processEngineConfiguration) {
        if (isV5Entity(processDefinition.getEngineVersion(), processDefinition.getId(), "process definition", processEngineConfiguration)) {
            return true;
        }

        return false;
    }

    public static boolean isV5Entity(String tag, String id, String entityType, ProcessEngineConfigurationImpl processEngineConfiguration) {
        if (isVersion5Tag(tag)) {
            if (!processEngineConfiguration.isFlowable5CompatibilityEnabled() || processEngineConfiguration.getFlowable5CompatibilityHandler() == null) {
                throw new FlowableException(entityType + " with id " + id + " has a v5 tag and flowable 5 compatibility is not enabled");
            }

            return true;

        } else {
            if (tag != null) {
                throw new FlowableException("Invalid 'engine' for " + entityType + " with id " + id + " : " + tag);
            }
            return false;
        }
    }

    public static boolean isVersion5Tag(String tag) {
        return V5_ENGINE_TAG.equals(tag) || "activiti-5".equals(tag);
    }

    public static Flowable5CompatibilityHandler getFlowable5CompatibilityHandler() {
        ProcessEngineConfigurationImpl processEngineConfiguration = CommandContextUtil.getProcessEngineConfiguration();

        Flowable5CompatibilityHandler flowable5CompatibilityHandler = null;
        if (processEngineConfiguration != null) {
            flowable5CompatibilityHandler = processEngineConfiguration.getFlowable5CompatibilityHandler();
        }

        if (flowable5CompatibilityHandler == null) {

View on GitHub (pinned to d6d39ce1c6)