{"record":{"id":"977db28d49446737","repo":"flowable/flowable-engine","slug":"the-bpmn-2-0-xml-is-not-properly-encoded","errorCode":null,"errorMessage":"The bpmn 2.0 xml is not properly encoded","messagePattern":"The bpmn 2\\.0 xml is not properly encoded","errorType":"exception","errorClass":"XMLException","httpStatus":null,"severity":"error","filePath":"modules/flowable-bpmn-converter/src/main/java/org/flowable/bpmn/converter/BpmnXMLConverter.java","lineNumber":299,"sourceCode":"        }\n        \n        if (xif.isPropertySupported(XMLConstants.ACCESS_EXTERNAL_DTD)) {\n            xif.setProperty(XMLConstants.ACCESS_EXTERNAL_DTD, \"\");\n        }\n        \n        if (xif.isPropertySupported(XMLConstants.ACCESS_EXTERNAL_SCHEMA)) {\n            xif.setProperty(XMLConstants.ACCESS_EXTERNAL_SCHEMA, \"\");\n        }\n\n        if (validateSchema) {\n            try (InputStreamReader in = new InputStreamReader(inputStreamProvider.getInputStream(), encoding)) {\n                if (!enableSafeBpmnXml) {\n                    validateModel(inputStreamProvider);\n                } else {\n                    validateModel(new FlowableXMLStreamReader(xif.createXMLStreamReader(in)));\n                }\n            } catch (UnsupportedEncodingException e) {\n                throw new XMLException(\"The bpmn 2.0 xml is not properly encoded\", e);\n            } catch(XMLStreamException e){\n                throw new XMLException(\"Error while reading the BPMN 2.0 XML\", e);\n            } catch(Exception e){\n                throw new XMLException(e.getMessage(), e);\n            }\n        }\n        // The input stream is closed after schema validation\n        try (InputStreamReader in = new InputStreamReader(inputStreamProvider.getInputStream(), encoding)) {\n            // XML conversion\n            return convertToBpmnModel(xif.createXMLStreamReader(in));\n        } catch (UnsupportedEncodingException e) {\n            throw new XMLException(\"The bpmn 2.0 xml is not properly encoded\", e);\n        } catch (XMLStreamException e) {\n            throw new XMLException(\"Error while reading the BPMN 2.0 XML\", e);\n        } catch (IOException e) {\n            throw new XMLException(e.getMessage(), e);\n        }\n    }","sourceCodeStart":281,"sourceCodeEnd":317,"githubUrl":"https://github.com/flowable/flowable-engine/blob/d6d39ce1c69ff244f2d9dc6af756a9b95e865586/modules/flowable-bpmn-converter/src/main/java/org/flowable/bpmn/converter/BpmnXMLConverter.java#L281-L317","documentation":"BpmnXMLConverter.convertToBpmnModel wraps UnsupportedEncodingException into XMLException('The bpmn 2.0 xml is not properly encoded'). The parser could not create an XML stream reader for the input using the requested character encoding (e.g. invalid or unavailable encoding name, or bytes not matching the declared encoding).","triggerScenarios":"Calling convertToBpmnModel(...) with an InputStream whose declared/requested encoding (inputStream encoding or DEFAULT_ENCODING parameter) is unsupported or misspelled, causing xif.createXMLStreamReader(in) to throw UnsupportedEncodingException.","commonSituations":"Passing a custom encoding string with a typo (e.g. 'utf-8 ' with whitespace or 'UTF8' variants) to the convertToBpmnModel overload with explicit encoding; XML documents with a wrong encoding declaration feeding a stream that can't be decoded; deployments where BPMN XML was saved with a broken/unknown charset.","solutions":["Validate the encoding name passed to convertToBpmnModel; use standard names like 'UTF-8'","Call the convertToBpmnModel overload that uses DEFAULT_ENCODING instead of a custom encoding","Re-save/re-export the BPMN XML file as UTF-8","Check the XML declaration encoding in the BPMN file matches the actual byte encoding","Catch XMLException around convertToBpmnModel and inspect the cause for the exact encoding problem"],"exampleFix":"// before\nconverter.convertToBpmnModel(inputStreamProvider, true, false, \"UTF8\");\n// after\nconverter.convertToBpmnModel(inputStreamProvider, true, false, \"UTF-8\");","handlingStrategy":"validation","validationCode":"private static boolean isValidEncoding(String enc) {\n    try {\n        return enc == null || !java.nio.charset.Charset.isSupported(enc);\n    } catch (Exception e) { return false; }\n}\n// use only when isValidEncoding returns false:\n// throw new IllegalArgumentException(\"Unsupported encoding: \" + enc);","typeGuard":null,"tryCatchPattern":"try {\n    BpmnModel model = converter.convertToBpmnModel(provider, validate, safeBpmn, encoding);\n} catch (XMLException e) {\n    if (e.getCause() instanceof java.io.UnsupportedEncodingException) {\n        throw new IllegalArgumentException(\"Bad encoding '\" + encoding + \"' for BPMN XML\", e);\n    }\n    throw e;\n}","preventionTips":["Use the standard name \"UTF-8\" for encodings passed to convertToBpmnModel","Prefer the DEFAULT_ENCODING overload unless a custom encoding is required","Ensure BPMN XML files are stored as UTF-8 with a matching XML declaration","Validate user-supplied encodings with Charset.isSupported before use"],"tags":["java","flowable","bpmn","encoding","xml"],"backgroundTag":"invalid-argument-format","analyzedSha":"d6d39ce1c69ff244f2d9dc6af756a9b95e865586","analyzedAt":"2026-09-11T06:41:19.413Z","contentChangedAt":"2026-09-11T06:41:19.413Z","schemaVersion":2},"datasetVersion":"2026-09-14T05:17:10.506Z"}