Invalid reference in diagram interchange definition

Error message

Invalid reference in diagram interchange definition: {} does not reference a flow node

What it means

In processDI(), a BPMNShape references an existing flow element that is not a FlowNode (e.g. a SequenceFlow or other non-node element). Shapes can only be drawn for flow nodes, so the engine warns and skips rendering that shape.

Solutions

Move the DI entry from BPMNShape to BPMNEdge (use bpmndi:BPMNEdge for sequence flows)
Regenerate the diagram from the modeler
Correct the bpmnElement attribute to reference the intended flow node id

Example fix

// before
<bpmndi:BPMNShape bpmnElement="flow1" ...>
// after
<bpmndi:BPMNEdge bpmnElement="flow1" ...>

Defensive patterns

Strategy: validation

Validate before calling

// Shapes must reference FlowNodes
for (Map.Entry<String, GraphicInfo> e : bpmnModel.getLocationMap().entrySet()) {
    FlowElement fe = bpmnModel.getFlowElement(e.getKey());
    if (fe != null && !(fe instanceof FlowNode))
        throw new IllegalArgumentException("BPMNShape must reference a FlowNode: " + e.getKey());
}

Prevention

Use BPMNEdge for sequence flows, BPMNShape only for nodes
Regenerate DI from the modeler instead of manual edits

When it happens

Trigger: A bpmndi:BPMNShape's bpmnElement attribute points to a FlowElement that is not a FlowNode — typically a sequenceFlow id — logged by BpmnParse.processDI().

Common situations: Modeler bug or manual edit placing a sequence flow id inside BPMNShape instead of BPMNEdge; mixing up shape/edge entries when hand-editing DI XML.

Related errors

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

Appendix: source

Thrown at modules/flowable5-engine/src/main/java/org/activiti/engine/impl/bpmn/parser/BpmnParse.java:358

    // Diagram interchange
    // /////////////////////////////////////////////////////////////////

    public void processDI() {
        if (!bpmnModel.getLocationMap().isEmpty()) {

            // Verify if all referenced elements exist
            for (String bpmnReference : bpmnModel.getLocationMap().keySet()) {
                if (bpmnModel.getFlowElement(bpmnReference) == null) {
                    // ACT-1625: don't warn when artifacts are referenced from DI
                    if (bpmnModel.getArtifact(bpmnReference) == null) {
                        // check if it's a Pool or Lane, then DI is ok
                        if (bpmnModel.getPool(bpmnReference) == null && bpmnModel.getLane(bpmnReference) == null) {
                            LOGGER.warn("Invalid reference in diagram interchange definition: could not find {}", bpmnReference);
                        }
                    }
                } else if (!(bpmnModel.getFlowElement(bpmnReference) instanceof FlowNode)) {
                    LOGGER.warn("Invalid reference in diagram interchange definition: {} does not reference a flow node", bpmnReference);
                }
            }
            for (String bpmnReference : bpmnModel.getFlowLocationMap().keySet()) {
                if (bpmnModel.getFlowElement(bpmnReference) == null) {
                    // ACT-1625: don't warn when artifacts are referenced from DI
                    if (bpmnModel.getArtifact(bpmnReference) == null) {
                        LOGGER.warn("Invalid reference in diagram interchange definition: could not find {}", bpmnReference);
                    }
                } else if (!(bpmnModel.getFlowElement(bpmnReference) instanceof SequenceFlow)) {
                    LOGGER.warn("Invalid reference in diagram interchange definition: {} does not reference a sequence flow", bpmnReference);
                }
            }

            for (Process process : bpmnModel.getProcesses()) {
                if (!process.isExecutable()) {
                    continue;
                }

View on GitHub (pinned to d6d39ce1c6)