{"record":{"id":"f60ed483d1580382","repo":"flowable/flowable-engine","slug":"error-parsing-historic-case-instance-migration-doc","errorCode":null,"errorMessage":"Error parsing Historic Case Instance Migration Document","messagePattern":"Error parsing Historic 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/HistoricCaseInstanceMigrationDocumentConverter.java","lineNumber":78,"sourceCode":"\n    public static HistoricCaseInstanceMigrationDocument convertFromJson(String jsonCaseInstanceMigrationDocument) {\n\n        try {\n            JsonNode rootNode = objectMapper.readTree(jsonCaseInstanceMigrationDocument);\n            HistoricCaseInstanceMigrationDocumentBuilderImpl documentBuilder = new HistoricCaseInstanceMigrationDocumentBuilderImpl();\n\n            documentBuilder.setCaseDefinitionToMigrateTo(getJsonProperty(TO_CASE_DEFINITION_ID_JSON_PROPERTY, rootNode));\n            \n            String caseDefinitionKey = getJsonProperty(TO_CASE_DEFINITION_KEY_JSON_PROPERTY, rootNode);\n            Integer caseDefinitionVersion = getJsonPropertyAsInteger(TO_CASE_DEFINITION_VERSION_JSON_PROPERTY, rootNode);\n            documentBuilder.setCaseDefinitionToMigrateTo(caseDefinitionKey, caseDefinitionVersion);\n\n            documentBuilder.setTenantId(getJsonProperty(TO_CASE_DEFINITION_TENANT_ID_JSON_PROPERTY, rootNode));\n\n            return documentBuilder.build();\n\n        } catch (JacksonException e) {\n            throw new FlowableException(\"Error parsing Historic Case Instance Migration Document\", e);\n        }\n\n    }\n    \n    protected static String getJsonProperty(String propertyName, JsonNode jsonNode) {\n        if (jsonNode.has(propertyName) && !jsonNode.get(propertyName).isNull()) {\n            return jsonNode.get(propertyName).asString();\n        }\n        \n        return null;\n    }\n    \n    protected static Integer getJsonPropertyAsInteger(String propertyName, JsonNode jsonNode) {\n        if (jsonNode.has(propertyName) && !jsonNode.get(propertyName).isNull()) {\n            return jsonNode.get(propertyName).asInt();\n        }\n        \n        return null;","sourceCodeStart":60,"sourceCodeEnd":96,"githubUrl":"https://github.com/flowable/flowable-engine/blob/d6d39ce1c69ff244f2d9dc6af756a9b95e865586/modules/flowable-cmmn-engine/src/main/java/org/flowable/cmmn/engine/impl/migration/HistoricCaseInstanceMigrationDocumentConverter.java#L60-L96","documentation":"HistoricCaseInstanceMigrationDocumentConverter.convertFromJson parses the migration document JSON with Jackson. Any JacksonException (malformed JSON, wrong node types, invalid structure) is wrapped and rethrown as this FlowableException with the Jackson exception as cause.","triggerScenarios":"Calling convertFromJson (e.g. when building a migration from a JSON document string/resource) where the JSON is syntactically invalid or contains fields with unexpected types (e.g. mappings where an array or object is expected).","commonSituations":"Hand-edited migration JSON files; JSON generated with wrong property names so nested structures don't match; passing a non-migration JSON file; encoding/newline corruption in resources.","solutions":["Validate the migration document JSON with a JSON linter/parser before passing it in.","Generate the document programmatically via HistoricCaseInstanceMigrationDocument or the builder API instead of hand-writing JSON.","Inspect the wrapped JacksonException cause for the exact line/problem.","Check property names against the converter's JSON constants (e.g. toCaseDefinitionKey, mappings)."],"exampleFix":"// before\nString doc = \"{ toCaseDefinitionKey: orderCase }\"; // unquoted key -> JacksonException\n// after\nString doc = \"{\\\"toCaseDefinitionKey\\\":\\\"orderCase\\\"}\";","handlingStrategy":"validation","validationCode":"new ObjectMapper().readTree(migrationJson); // throws JsonProcessingException before engine sees it","typeGuard":"try { JsonNode n = new ObjectMapper().readTree(json); return n != null && n.isObject(); } catch (JsonProcessingException e) { return false; }","tryCatchPattern":"try { document = converter.convertFromJson(jsonStream); } catch (FlowableException e) { if (e.getMessage().equals(\"Error parsing Historic Case Instance Migration Document\")) { log(\"Bad migration JSON\", e.getCause()); } throw e; }","preventionTips":["Generate migration documents via the builder API instead of hand-written JSON.","Lint all migration JSON in CI.","Version-control and review migration documents like code.","Always check the cause JacksonException for precise error location."],"tags":["cmmn","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"}