{"record":{"id":"d6dc74a6e8ea535d","repo":"flowable/flowable-engine","slug":"must-specify-a-historic-case-instance-migration-do-d6dc74","errorCode":null,"errorMessage":"Must specify a historic case instance migration document to migrate","messagePattern":"Must specify a historic case instance migration document to migrate","errorType":"exception","errorClass":"FlowableException","httpStatus":null,"severity":"error","filePath":"modules/flowable-cmmn-engine/src/main/java/org/flowable/cmmn/engine/impl/cmd/HistoricCaseInstanceMigrationCmd.java","lineNumber":41,"sourceCode":"public class HistoricCaseInstanceMigrationCmd implements Command<Void> {\n    \n    protected CmmnEngineConfiguration cmmnEngineConfiguration;\n\n    protected String caseInstanceId;\n    protected String caseDefinitionId;\n    protected String caseDefinitionKey;\n    protected int caseDefinitionVersion;\n    protected String caseDefinitionTenantId;\n    protected HistoricCaseInstanceMigrationDocument historicCaseInstanceMigrationDocument;\n\n    public HistoricCaseInstanceMigrationCmd(String caseInstanceId, HistoricCaseInstanceMigrationDocument historicCaseInstanceMigrationDocument,\n            CmmnEngineConfiguration cmmnEngineConfiguration) {\n        \n        if (caseInstanceId == null) {\n            throw new FlowableException(\"Must specify a historic case instance id to migrate\");\n        }\n        if (historicCaseInstanceMigrationDocument == null) {\n            throw new FlowableException(\"Must specify a historic case instance migration document to migrate\");\n        }\n        \n        this.caseInstanceId = caseInstanceId;\n        this.historicCaseInstanceMigrationDocument = historicCaseInstanceMigrationDocument;\n        this.cmmnEngineConfiguration = cmmnEngineConfiguration;\n    }\n\n    public HistoricCaseInstanceMigrationCmd(HistoricCaseInstanceMigrationDocument historicCaseInstanceMigrationDocument, String caseDefinitionId,\n            CmmnEngineConfiguration cmmnEngineConfiguration) {\n        \n        if (caseDefinitionId == null) {\n            throw new FlowableException(\"Must specify a case definition id to migrate\");\n        }\n        if (historicCaseInstanceMigrationDocument == null) {\n            throw new FlowableException(\"Must specify a historic case instance migration document to migrate\");\n        }\n        \n        this.caseDefinitionId = caseDefinitionId;","sourceCodeStart":23,"sourceCodeEnd":59,"githubUrl":"https://github.com/flowable/flowable-engine/blob/d6d39ce1c69ff244f2d9dc6af756a9b95e865586/modules/flowable-cmmn-engine/src/main/java/org/flowable/cmmn/engine/impl/cmd/HistoricCaseInstanceMigrationCmd.java#L23-L59","documentation":"For single-instance historic migration, the HistoricCaseInstanceMigrationDocument carries the mapping of the historic case/plan-item states to the new case definition. A null document leaves the migration undefined, so the constructor throws this FlowableException right away.","triggerScenarios":"Calling new HistoricCaseInstanceMigrationCmd(caseInstanceId, null, cmmnEngineConfiguration) — typically when HistoricCaseInstanceMigrationBuilder was created but no mappings (migrateCaseDefinitionTo, map... ) were added, or the parsed document variable was null.","commonSituations":"Builder misuse (forgot to build the document); JSON migration document file missing or unparsable; a helper returning null on error that the caller passed straight through.","solutions":["Build the document first with the HistoricCaseInstanceMigrationBuilder (via cmmnEngineConfiguration.getCaseInstanceMigrationManager()) and pass the result.","If loading from JSON, use HistoricCaseInstanceMigrationDocument.fromJson(json) and verify non-null before constructing.","Add a caller-side null assertion for the document."],"exampleFix":"// before\nnew HistoricCaseInstanceMigrationCmd(caseInstanceId, doc, cfg); // doc == null\n\n// after\nHistoricCaseInstanceMigrationDocument doc = migrationManager\n    .createHistoricCaseInstanceMigrationBuilder()\n    .migrateCaseDefinitionTo(newDefinitionId)\n    .build();\nnew HistoricCaseInstanceMigrationCmd(caseInstanceId, doc, cfg);","handlingStrategy":"validation","validationCode":"if (doc == null)\n    throw new IllegalArgumentException(\"Build the HistoricCaseInstanceMigrationDocument before migrating a historic case instance\");","typeGuard":"boolean isMigrationReady(String instanceId, HistoricCaseInstanceMigrationDocument doc) {\n    return instanceId != null && doc != null;\n}","tryCatchPattern":"try {\n    execute(new HistoricCaseInstanceMigrationCmd(caseInstanceId, doc, cfg));\n} catch (FlowableException e) {\n    if (e.getMessage().contains(\"migration document\")) {\n        throw new ConfigurationException(\"Finish the HistoricCaseInstanceMigrationBuilder chain to obtain a document\", e);\n    }\n    throw e;\n}","preventionTips":["Call build() on the migration builder before using its result","Validate fromJson() output when loading documents from disk","Reuse one factory method for all migration document creation"],"tags":["flowable","cmmn","null-argument","migration-document","case-migration"],"backgroundTag":"null-argument","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"}