{"record":{"id":"1bcea5310120cb3d","repo":"flowable/flowable-engine","slug":"error-parsing-process-instance-migration-document","errorCode":null,"errorMessage":"Error parsing Process Instance Migration Document","messagePattern":"Error parsing Process Instance Migration Document","errorType":"exception","errorClass":"FlowableException","httpStatus":null,"severity":"error","filePath":"modules/flowable-engine/src/main/java/org/flowable/engine/migration/ProcessInstanceMigrationDocumentConverter.java","lineNumber":268,"sourceCode":"\n                for (JsonNode mappingNode : enableActivityMappings) {\n                    if (mappingNode.hasNonNull(ProcessInstanceMigrationDocumentConstants.ACTIVITY_ID_JSON_PROPERTY)) {\n                        EnableActivityMapping.EnableMapping enableMapping = new EnableActivityMapping.EnableMapping(\n                                mappingNode.get(ProcessInstanceMigrationDocumentConstants.ACTIVITY_ID_JSON_PROPERTY).asString());\n                        documentBuilder.addEnableActivityMapping(enableMapping);\n                    }\n                }\n            }\n\n            JsonNode processInstanceVariablesNode = rootNode.get(ProcessInstanceMigrationDocumentConstants.PROCESS_INSTANCE_VARIABLES_JSON_SECTION);\n            if (processInstanceVariablesNode != null) {\n                Map<String, Object> processInstanceVariables = ProcessInstanceMigrationDocumentConverter.convertFromJsonNodeToObject(processInstanceVariablesNode, objectMapper);\n                documentBuilder.addProcessInstanceVariables(processInstanceVariables);\n            }\n            return documentBuilder.build();\n\n        } catch (JacksonException e) {\n            throw new FlowableException(\"Error parsing Process Instance Migration Document\", e);\n        }\n\n    }\n\n    protected static JsonNode convertToJsonProcessInstanceVariables(ProcessInstanceMigrationDocument processInstanceMigrationDocument, ObjectMapper objectMapper) {\n        Map<String, Object> processInstanceVariables = processInstanceMigrationDocument.getProcessInstanceVariables();\n        if (processInstanceVariables != null && !processInstanceVariables.isEmpty()) {\n            return objectMapper.valueToTree(processInstanceVariables);\n        }\n        return null;\n    }\n\n    protected static JsonNode convertToJsonUpgradeScript(Script script, ObjectMapper objectMapper) {\n        if (script != null) {\n            return objectMapper.valueToTree(script);\n        }\n        return null;\n    }","sourceCodeStart":250,"sourceCodeEnd":286,"githubUrl":"https://github.com/flowable/flowable-engine/blob/d6d39ce1c69ff244f2d9dc6af756a9b95e865586/modules/flowable-engine/src/main/java/org/flowable/engine/migration/ProcessInstanceMigrationDocumentConverter.java#L250-L286","documentation":"Wrapping error thrown when the Jackson ObjectMapper fails to parse a JSON document while deserializing a Process Instance Migration Document (convertFromJson). The original JacksonException is attached as the cause.","triggerScenarios":"Calling ProcessInstanceMigrationDocumentConverter.convertFromJson with a malformed JSON string/stream, wrong content type, or truncated JSON — Jackson throws JacksonException during parsing of any node in the migration document.","commonSituations":"Hand-edited migration JSON with syntax errors; file saved with BOM or wrong encoding; passing a non-JSON payload (e.g. XML or empty string) to the converter; response from an HTTP API cut off.","solutions":["Validate the migration JSON with a JSON linter/parser before calling convertFromJson.","Inspect the cause (JacksonException) message for exact line/character of the syntax error.","Regenerate the document using ProcessInstanceMigrationBuilder and migrateProcessInstances() serialization instead of hand-writing JSON.","Ensure the input is read fully and as UTF-8 without BOM."],"exampleFix":"// before\nString bad = \"{ \\\"migrations\\\": [ }\"; // malformed\ndocument = ProcessInstanceMigrationDocumentConverter.convert(bad);\n\n// after\nString good = \"{ \\\"migrations\\\": [] }\"; // validated JSON\nObjectNode node = (ObjectNode) new ObjectMapper().readTree(good); // pre-validate\ndocument = ProcessInstanceMigrationDocumentConverter.convert(node);","handlingStrategy":"try-catch","validationCode":"try (Parser p = new JsonParser()) { p.parse(json); } // or objectMapper.readTree(json) as pre-check","typeGuard":null,"tryCatchPattern":"try {\n    doc = ProcessInstanceMigrationDocumentConverter.convert(json);\n} catch (FlowableException e) {\n    logger.error(\"Invalid migration document JSON\", e.getCause());\n    throw new IllegalArgumentException(\"Malformed migration document\", e);\n}","preventionTips":["Generate migration documents via ProcessInstanceMigrationBuilder instead of hand-writing JSON","Validate JSON with a linter or objectMapper.readTree before converting","Ensure UTF-8 encoding without BOM when reading documents from files or HTTP"],"tags":["json","migration","parsing"],"backgroundTag":"json-parse-error","analyzedSha":"d6d39ce1c69ff244f2d9dc6af756a9b95e865586","analyzedAt":"2026-09-11T06:41:19.413Z","contentChangedAt":"2026-09-11T06:41:19.413Z","schemaVersion":2},"datasetVersion":"2026-09-18T11:17:12.947Z"}