Could not find matching parse handler for planItem

Error message

Could not find matching parse handler for planItem '{}' with planItemDefinition '{}'. This is likely a bug.

What it means

CmmnParseHandlers.parseElement logs this warning when a PlanItem's planItemDefinition class has no registered CmmnParseHandler. The plan item is silently skipped during parsing, so its behavior is never wired — the log says 'This is likely a bug' because the engine normally registers a handler for every supported definition type.

Solutions

Inspect the plan item definition in the CMMN XML and confirm the element type is supported by your Flowable version.
Upgrade/downgrade Flowable so the definition type has a registered handler.
If using custom plan item definitions, register a matching CmmnParseHandler in the CmmnEngineConfiguration.
Fix typos/namespace issues in the CMMN XML causing an unexpected definition class to be created.

Example fix

// before (unsupported definition)
<planItem id="pi1"><standardEvent>complete</standardEvent><flowable:myCustomType/></planItem>
// after
<planItem id="pi1"><standardEvent>complete</standardEvent><task isBlocking="true"/></planItem>

Defensive patterns

Strategy: validation

Validate before calling

// Pre-check CMMN XML only uses supported plan item definition types
Set<String> supported = Set.of("task", "humanTask", "caseTask", "processTask", "decisionTask",
    "eventListener", "userEventListener", "milestone", "stage", "planFragment");
// parse each <planItem>'s child element local-name against 'supported' before deploying

Try / catch

null

Prevention

Validate CMMN XML against the Flowable-supported element set before deployment.
Keep engine and CMMN model versions aligned across upgrades.
Register parse handlers for any custom plan item definitions.

When it happens

Trigger: Parsing a CMMN XML whose plan item references a planItemDefinition type the parser has no handler for — typically a custom/unknown element type or an engine version missing handler registration for that definition class.

Common situations: CMMN XML using vendor extension or unsupported case task types; engine upgrade/downgrade where a handler class was added/removed; custom plan item definitions registered without a matching parse handler.

Understand the failure class

Background: UnsupportedOperationException and "is not supported" errors: when a library deliberately refuses a call — this error's family across 30 libraries.

Related errors

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

Appendix: source

Thrown at modules/flowable-cmmn-engine/src/main/java/org/flowable/cmmn/engine/impl/parser/CmmnParseHandlers.java:61

    }

    public void addHandler(CmmnParseHandler cmmnParseHandler) {
        for (Class<? extends BaseElement> type : cmmnParseHandler.getHandledTypes()) {
            parseHandlers
                .computeIfAbsent(type, key -> new ArrayList<>())
                .add(cmmnParseHandler);
        }
    }

    public void parseElement(CmmnParser cmmnParser, CmmnParseResult cmmnParseResult, BaseElement baseElement) {

        List<CmmnParseHandler> handlers = null;
        if (baseElement instanceof PlanItem planItem) {
            // The plan item definition defines the actual behavior
            handlers = parseHandlers.get(planItem.getPlanItemDefinition().getClass());

            if (handlers == null) {
                LOGGER.warn("Could not find matching parse handler for planItem '{}' with planItemDefinition '{}'. This is likely a bug.",
                    baseElement.getId(), planItem.getPlanItemDefinition());

            } else {
                handlers.forEach(handler -> handler.parse(cmmnParser, cmmnParseResult, planItem)); // Note: passing plan item, NOT plan item definition

            }

        } else {
            handlers = parseHandlers.get(baseElement.getClass());
            if (handlers == null) {
                LOGGER.warn("Could not find matching parse handler for '{}' this is likely a bug.", baseElement.getId());

            } else {
                handlers.forEach(handler -> handler.parse(cmmnParser, cmmnParseResult, baseElement));

            }

        }

View on GitHub (pinned to d6d39ce1c6)