{"record":{"id":"d5570376410ecbc7","repo":"flowable/flowable-engine","slug":"error-processing-bpmn-document","errorCode":null,"errorMessage":"Error processing BPMN document","messagePattern":"Error processing BPMN document","errorType":"exception","errorClass":"XMLException","httpStatus":null,"severity":"error","filePath":"modules/flowable-bpmn-converter/src/main/java/org/flowable/bpmn/converter/BpmnXMLConverter.java","lineNumber":478,"sourceCode":"                    }\n                }\n            }\n\n            for (Process process : model.getProcesses()) {\n                for (Pool pool : model.getPools()) {\n                    if (process.getId().equals(pool.getProcessRef())) {\n                        pool.setExecutable(process.isExecutable());\n                    }\n                }\n                processFlowElements(process.getFlowElements(), process);\n            }\n\n        } catch (XMLException e) {\n            throw e;\n\n        } catch (Exception e) {\n            LOGGER.error(\"Error processing BPMN document\", e);\n            throw new XMLException(\"Error processing BPMN document\", e);\n        }\n        return model;\n    }\n\n    protected void processFlowElements(Collection<FlowElement> flowElementList, BaseElement parentScope) {\n        for (FlowElement flowElement : flowElementList) {\n\n            if (flowElement instanceof SequenceFlow sequenceFlow) {\n                FlowNode sourceNode = getFlowNodeFromScope(sequenceFlow.getSourceRef(), parentScope);\n                if (sourceNode != null) {\n                    sourceNode.getOutgoingFlows().add(sequenceFlow);\n                    sequenceFlow.setSourceFlowElement(sourceNode);\n                }\n\n                FlowNode targetNode = getFlowNodeFromScope(sequenceFlow.getTargetRef(), parentScope);\n                if (targetNode != null) {\n                    targetNode.getIncomingFlows().add(sequenceFlow);\n                    sequenceFlow.setTargetFlowElement(targetNode);","sourceCodeStart":460,"sourceCodeEnd":496,"githubUrl":"https://github.com/flowable/flowable-engine/blob/d6d39ce1c69ff244f2d9dc6af756a9b95e865586/modules/flowable-bpmn-converter/src/main/java/org/flowable/bpmn/converter/BpmnXMLConverter.java#L460-L496","documentation":"Top-level catch in convertToBpmnModel(XMLStreamReader): any Exception that is not already an XMLException (parse errors are rethrown unchanged) is logged with 'Error processing BPMN document' and wrapped in XMLException with this message. It signals an unexpected failure during model building — usually a converter bug or a semantically invalid model rather than pure XML syntax.","triggerScenarios":"An unexpected RuntimeException/Exception thrown while converting elements to the BpmnModel (e.g. NPE in a converter for an unusual element, ArrayIndexOutOfBounds on malformed attributes, ClassCastException) during convertToBpmnModel(XMLStreamReader).","commonSituations":"BPMN files with elements the converter doesn't expect (rare vendor extensions, wrong attribute types), Flowable version incompatibilities where a newer modeler emits elements an older converter mishandles, or bugs in custom converters registered into the XML converter.","solutions":["Read the logged stack trace (LOGGER.error output) — the cause identifies the exact element/converter that failed.","Open the BPMN file in the Flowable modeler and re-save to normalize nonstandard constructs.","Check Flowable version compatibility between the tool that generated the XML and the runtime converter; upgrade flowable-bpmn-converter if needed.","If a custom converter/extension is involved, fix its handling of the offending element."],"exampleFix":"// before\ncatch (XMLException e) { throw e; } // other exceptions fall through to generic wrap\n// after (caller side)\ntry {\n    BpmnModel m = converter.convertToBpmnModel(xtr);\n} catch (XMLException e) {\n    logger.error(\"Processing failed at element\", e.getCause()); // inspect real cause\n    throw e;\n}","handlingStrategy":"try-catch","validationCode":null,"typeGuard":null,"tryCatchPattern":"try {\n    return converter.convertToBpmnModel(xtr);\n} catch (XMLException e) {\n    if (\"Error processing BPMN document\".equals(e.getMessage())) {\n        // non-XMLException failure during model building — cause has the real stack\n        throw new DeploymentException(\"Unexpected converter failure: \" + e.getCause(), e);\n    }\n    throw e; // pure XML parse problems propagate as-is\n}","preventionTips":["Read the LOGGER.error stack trace to identify the failing element/converter","Keep flowable-bpmn-converter and the modeler on compatible versions","Round-trip models through the Flowable modeler to normalize vendor extensions","Unit-test custom element converters against sample models"],"tags":["java","bpmn","converter","unexpected-exception"],"backgroundTag":"internal-invariant-violation","analyzedSha":"d6d39ce1c69ff244f2d9dc6af756a9b95e865586","analyzedAt":"2026-09-11T06:41:19.413Z","contentChangedAt":"2026-09-11T06:41:19.413Z","schemaVersion":2},"datasetVersion":"2026-09-14T11:17:12.474Z"}