flowable/flowable-engine · error · FlowableException

{planItemInstanceEntity} does not have a behavior

Error message

{planItemInstanceEntity} does not have a behavior

What it means

StartPlanItemInstanceOperation.executeActivityBehavior resolves a CmmnActivityBehavior for the plan item and executes it. If no behavior class is configured (or it cannot be instantiated to a CoreCmmnActivityBehavior/behavior at all), the engine has nothing to run and throws a FlowableException stating the plan item instance has no behavior.

Source

Thrown at modules/flowable-cmmn-engine/src/main/java/org/flowable/cmmn/engine/impl/agenda/operation/StartPlanItemInstanceOperation.java:91

        CommandContextUtil.getCmmnHistoryManager(commandContext).recordPlanItemInstanceStarted(planItemInstanceEntity);
    }

    protected void executeActivityBehavior() {
        CmmnActivityBehavior activityBehavior = (CmmnActivityBehavior) planItemInstanceEntity.getPlanItem().getBehavior();
        if (migrationContext != null && activityBehavior instanceof CmmnActivityWithMigrationContextBehavior) {
            ((CmmnActivityWithMigrationContextBehavior) activityBehavior).execute(commandContext, planItemInstanceEntity, migrationContext);
            
        } else if (activityBehavior instanceof ChildTaskActivityBehavior) {
            ((ChildTaskActivityBehavior) activityBehavior).execute(commandContext, planItemInstanceEntity, childTaskVariableInfo);
            
        } else if (activityBehavior instanceof CoreCmmnActivityBehavior) {
            ((CoreCmmnActivityBehavior) activityBehavior).execute(commandContext, planItemInstanceEntity);
            
        } else if (activityBehavior != null) {
            activityBehavior.execute(planItemInstanceEntity);

        } else {
            throw new FlowableException(planItemInstanceEntity + " does not have a behavior");

        }
    }

    @Override
    public String getOperationName() {
        return "[Start plan item]";
    }
    
}

View on GitHub (pinned to d6d39ce1c6)

Solutions

1. Register a behavior for the plan item definition type (PlanItemBehaviorFactory / CmmnEngineConfiguration behavior mapping).
2. Verify the custom behavior class name and that it is on the engine's classpath.
3. Use a supported standard plan item definition type (humanTask, serviceTask, eventListener, ...) instead of an unmapped custom type.
4. Check CmmnEngineConfiguration bean overrides did not wipe default behavior factories.

Example fix

// before: custom definition type with no behavior
cmmnEngineConfiguration.setPlanItemBehaviorFactory(null);
// after
DefaultPlanItemBehaviorFactory factory = new DefaultPlanItemBehaviorFactory();
factory.addPlanItemDefinitionBehavior("myCustomTask", MyCustomTaskBehavior.class);
cmmnEngineConfiguration.setPlanItemBehaviorFactory(factory);

// java: verify behavior configured for the definition type
CmmnEngineConfiguration cfg = (CmmnEngineConfiguration)
    cmmnEngine.getCmmnEngineConfiguration();
if (cfg.getPlanItemBehaviorFactory() == null)
    throw new IllegalStateException("No PlanItemBehaviorFactory configured");

try {
    startPlanItem();
} catch (FlowableException e) {
    if (e.getMessage().endsWith("does not have a behavior")) {
        // register behavior for the plan item definition type
    }
}

When it happens

Trigger: A plan item definition (e.g. HumanTask, ServiceTask, custom PlanItemDefinition) whose behaviorClass is not set or resolves to null in the CmmnEngineConfiguration / case definition when the agenda starts the plan item.

Common situations: Custom plan item definition types without a registered PlanItemBehaviorFactory mapping; engine configuration missing a custom behavior class on the classpath; typo in behaviorClass attribute.

Understand the failure class

Background: "not installed", "pip install", "required for": how missing-dependency errors surface across open-source libraries — this error's family across 34 libraries.

Related errors

• Could not find an implementation of the org.flowable.cdi.imp
• no SMTP host is configured for the default mail server
• no SMTP host is configured for the mail server for tenant {t
• The mail client provider is not an instance of DefaultMailCl
• couldn't initialize cmmn engine from spring configuration re

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