flowable/flowable-engine · error · FlowableException

Must specify a historic case instance migration document to

Error message

Must specify a historic case instance migration document to migrate

What it means

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.

Source

Thrown at modules/flowable-cmmn-engine/src/main/java/org/flowable/cmmn/engine/impl/cmd/HistoricCaseInstanceMigrationCmd.java:41

public class HistoricCaseInstanceMigrationCmd implements Command<Void> {
    
    protected CmmnEngineConfiguration cmmnEngineConfiguration;

    protected String caseInstanceId;
    protected String caseDefinitionId;
    protected String caseDefinitionKey;
    protected int caseDefinitionVersion;
    protected String caseDefinitionTenantId;
    protected HistoricCaseInstanceMigrationDocument historicCaseInstanceMigrationDocument;

    public HistoricCaseInstanceMigrationCmd(String caseInstanceId, HistoricCaseInstanceMigrationDocument historicCaseInstanceMigrationDocument,
            CmmnEngineConfiguration cmmnEngineConfiguration) {
        
        if (caseInstanceId == null) {
            throw new FlowableException("Must specify a historic case instance id to migrate");
        }
        if (historicCaseInstanceMigrationDocument == null) {
            throw new FlowableException("Must specify a historic case instance migration document to migrate");
        }
        
        this.caseInstanceId = caseInstanceId;
        this.historicCaseInstanceMigrationDocument = historicCaseInstanceMigrationDocument;
        this.cmmnEngineConfiguration = cmmnEngineConfiguration;
    }

    public HistoricCaseInstanceMigrationCmd(HistoricCaseInstanceMigrationDocument historicCaseInstanceMigrationDocument, String caseDefinitionId,
            CmmnEngineConfiguration cmmnEngineConfiguration) {
        
        if (caseDefinitionId == null) {
            throw new FlowableException("Must specify a case definition id to migrate");
        }
        if (historicCaseInstanceMigrationDocument == null) {
            throw new FlowableException("Must specify a historic case instance migration document to migrate");
        }
        
        this.caseDefinitionId = caseDefinitionId;

View on GitHub (pinned to d6d39ce1c6)

Solutions

  1. Build the document first with the HistoricCaseInstanceMigrationBuilder (via cmmnEngineConfiguration.getCaseInstanceMigrationManager()) and pass the result.
  2. If loading from JSON, use HistoricCaseInstanceMigrationDocument.fromJson(json) and verify non-null before constructing.
  3. Add a caller-side null assertion for the document.

Example fix

// before
new HistoricCaseInstanceMigrationCmd(caseInstanceId, doc, cfg); // doc == null

// after
HistoricCaseInstanceMigrationDocument doc = migrationManager
    .createHistoricCaseInstanceMigrationBuilder()
    .migrateCaseDefinitionTo(newDefinitionId)
    .build();
new HistoricCaseInstanceMigrationCmd(caseInstanceId, doc, cfg);
Defensive patterns

Strategy: validation

Validate before calling

if (doc == null)
    throw new IllegalArgumentException("Build the HistoricCaseInstanceMigrationDocument before migrating a historic case instance");

Type guard

boolean isMigrationReady(String instanceId, HistoricCaseInstanceMigrationDocument doc) {
    return instanceId != null && doc != null;
}

Try / catch

try {
    execute(new HistoricCaseInstanceMigrationCmd(caseInstanceId, doc, cfg));
} catch (FlowableException e) {
    if (e.getMessage().contains("migration document")) {
        throw new ConfigurationException("Finish the HistoricCaseInstanceMigrationBuilder chain to obtain a document", e);
    }
    throw e;
}

Prevention

When it happens

Trigger: 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.

Common situations: 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.

Related errors

AI-assisted analysis of flowable/flowable-engine@d6d39ce1c6 (2026-09-11). Data as JSON: /api/errors/d6dc74a6e8ea535d. Report an issue: GitHub.