flowable/flowable-engine · warning

Could not find matching parse handler for

Error message

Could not find matching parse handler for '{}' this is likely a bug.

What it means

CmmnParseHandlers walks the parsed CMMN model and, for each BaseElement, looks up registered CmmnParseHandlers keyed by the element's class. When an element class has no registered handler, this warning is logged and the element is silently skipped rather than failing deployment. Flowable treats it as a bug because every model element type it can produce should have a handler registered.

Solutions

1. Check that the engine version matches the modeler/designer version used to produce the CMMN XML, and upgrade the flowable-cmmn-engine dependency if the XML uses newer element types
2. Inspect the element id logged in the warning, find its class in the CmmnModel, and register a handler: cmmnEngineConfiguration.getCmmnParser().addParseHandler(MyElement.class, myHandler)
3. Remove or fix the unsupported element in the CMMN XML if it is not needed
4. If it appears with stock XML and matching versions, report it to Flowable as a bug with the model attached

Example fix

// before: element has no handler, silently skipped
CmmnParser parser = cmmnEngineConfiguration.getCmmnParser();
// after: register a handler for the missing element type
parser.addParseHandler(MyCustomElement.class, (cmmnParser, result, element) -> {
    // parse logic for the element
});

CmmnModel model = new CmmnXmlConverter().convertToCmmnModel(xml, true, false, "UTF-8");
Set<Class<?>> handled = cmmnParser.getParseHandlers().keySet();
List<BaseElement> unhandled = collectElements(model).stream()
    .filter(e -> !handled.contains(e.getClass())).collect(Collectors.toList());
if (!unhandled.isEmpty()) throw new IllegalStateException("Unhandled elements: " + unhandled);

When it happens

Trigger: Parsing/deploying a CMMN XML whose model contains an element class not present in the parseHandlers map — e.g. a custom element type, an element added in a newer Flowable XSD being parsed by an older engine, or programmatic construction of a CmmnModel with element types the parser never registers.

Common situations: Deploying CMMN XML produced by a newer Flowable modeler into an older engine runtime; subclassing CMMN elements in custom code without registering a handler via CmmnParserImpl.addParseHandler; a Flowable bug for a newly introduced element type.

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

• byte array for resource
• bytes array is null
• cmmn bytes is null
• Could not find deployment with id
• Could not find matching parse handler for planItem

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

Appendix: source

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

        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)