{"record":{"id":"2b80386bc5e9c2eb","repo":"flowable/flowable-engine","slug":"error-parsing-case-instance-migration-document","errorCode":null,"errorMessage":"Error parsing Case Instance Migration Document","messagePattern":"Error parsing Case Instance Migration Document","errorType":"exception","errorClass":"FlowableException","httpStatus":null,"severity":"error","filePath":"modules/flowable-cmmn-engine/src/main/java/org/flowable/cmmn/engine/impl/migration/CaseInstanceMigrationDocumentConverter.java","lineNumber":501,"sourceCode":"                }\n            }\n\n            JsonNode caseInstanceVariablesNode = rootNode.get(CASE_INSTANCE_VARIABLES_JSON_SECTION);\n            if (caseInstanceVariablesNode != null) {\n                Map<String, Object> caseInstanceVariables = convertFromJsonNodeToObject(caseInstanceVariablesNode, objectMapper);\n                documentBuilder.addCaseInstanceVariables(caseInstanceVariables);\n            }\n\n            String preUpgradeExpression = getJsonProperty(PRE_UPGRADE_EXPRESSION_KEY_JSON_PROPERTY, rootNode);\n            documentBuilder.preUpgradeExpression(preUpgradeExpression);\n\n            String postUpgradeExpression = getJsonProperty(POST_UPGRADE_EXPRESSION_KEY_JSON_PROPERTY, rootNode);\n            documentBuilder.postUpgradeExpression(postUpgradeExpression);\n\n            return documentBuilder.build();\n\n        } catch (JacksonException e) {\n            throw new FlowableException(\"Error parsing Case Instance Migration Document\", e);\n        }\n    }\n\n    protected static JsonNode convertToJsonCaseInstanceVariables(CaseInstanceMigrationDocument caseInstanceMigrationDocument, ObjectMapper objectMapper) {\n        Map<String, Object> caseInstanceVariables = caseInstanceMigrationDocument.getCaseInstanceVariables();\n        if (caseInstanceVariables != null && !caseInstanceVariables.isEmpty()) {\n            return objectMapper.valueToTree(caseInstanceVariables);\n        }\n        return null;\n    }\n    \n    protected static <T> T convertFromJsonNodeToObject(JsonNode jsonNode, ObjectMapper objectMapper) {\n        return objectMapper.convertValue(jsonNode, new TypeReference<>() {\n\n        });\n    }\n    \n    protected static String getJsonProperty(String propertyName, JsonNode jsonNode) {","sourceCodeStart":483,"sourceCodeEnd":519,"githubUrl":"https://github.com/flowable/flowable-engine/blob/d6d39ce1c69ff244f2d9dc6af756a9b95e865586/modules/flowable-cmmn-engine/src/main/java/org/flowable/cmmn/engine/impl/migration/CaseInstanceMigrationDocumentConverter.java#L483-L519","documentation":"CaseInstanceMigrationDocumentConverter.convertFromJson parses a migration document JSON payload with Jackson. Any JacksonException during parsing (malformed JSON, wrong types for fields, unexpected node shapes) is wrapped in this FlowableException.","triggerScenarios":"Calling convertFromJson (e.g. via migration APIs that accept a JSON migration document string) with syntactically invalid JSON, a JSON value of the wrong type (e.g. variables as an array instead of an object), or a corrupted document.","commonSituations":"Hand-authoring migration JSON with typos; copying document JSON from logs with truncation; version mismatch where the document was produced by a different Flowable version with a changed schema; passing an empty string.","solutions":["Validate the migration document JSON with a JSON linter/parser before passing it","Compare the document against the expected schema (caseInstanceId, migrateToCaseDefinition, variables, etc.) and fix types/names","Regenerate the document programmatically via CaseInstanceMigrationDocumentBuilder instead of hand-writing it","Ensure the Flowable version producing and consuming the document matches"],"exampleFix":"// before\nString json = \"{ \\\"migrateToCaseDefinition\\\": { \\\"key\\\": \"; // malformed\nconverter.convertFromJson(json);\n// after\nString json = \"{\\\"migrateToCaseDefinition\\\":{\\\"key\\\":\\\"myCase\\\",\\\"version\\\":2}}\";\nconverter.convertFromJson(json);","handlingStrategy":"try-catch","validationCode":"let doc;\ntry { doc = JSON.parse(migrationJson); } catch (e) { throw new Error('Migration document is not valid JSON: ' + e.message); }\nif (!doc.migrateToCaseDefinition || !doc.migrateToCaseDefinition.key) throw new Error('Migration document missing migrateToCaseDefinition.key');","typeGuard":"function isValidMigrationDoc(json) { try { const d = JSON.parse(json); return d != null && typeof d === 'object'; } catch { return false; } }","tryCatchPattern":"try { converter.convertFromJson(json); } catch (e) { if (String(e.message).includes('Error parsing Case Instance Migration Document')) { logJsonError(json, e.getCause ? e.getCause() : e); } else { throw e; } }","preventionTips":["Build documents with CaseInstanceMigrationDocumentBuilder instead of hand-writing JSON","Run documents through a JSON schema validator before conversion","Pin Flowable versions so producer and consumer schemas match"],"tags":["json","migration","cmmn","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"}