flowable/flowable-engine · error · FlowableException

Must specify a historic case instance id to migrate

Error message

Must specify a historic case instance id to migrate

What it means

HistoricCaseInstanceMigrationCmd migrates a single historic case instance, so its constructor requires the caseInstanceId. When it is null the command throws FlowableException immediately: without an instance id there is nothing to migrate and no sensible lookup can be performed.

Source

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

import org.flowable.common.engine.impl.interceptor.Command;
import org.flowable.common.engine.impl.interceptor.CommandContext;

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");

View on GitHub (pinned to d6d39ce1c6)

Solutions

  1. Obtain a valid historic case instance id via cmmnHistoryService.createHistoricCaseInstanceQuery().caseDefinitionKey(...)...singleResult().getId() before constructing the command.
  2. Null-check the id at the call site and skip/error per instance rather than passing null into the command.
  3. Confirm you are querying the same CMMN engine configuration/database that contains the historic instances.

Example fix

// before
HistoricCaseInstance instance = query.singleResult(); // may be null
new HistoricCaseInstanceMigrationCmd(instance != null ? instance.getId() : null, doc, cfg);

// after
HistoricCaseInstance instance = query.singleResult();
if (instance == null) throw new IllegalStateException("No historic case instance found");
new HistoricCaseInstanceMigrationCmd(instance.getId(), doc, cfg);
Defensive patterns

Strategy: validation

Validate before calling

if (caseInstanceId == null || caseInstanceId.isBlank())
    throw new IllegalArgumentException("caseInstanceId required for historic case migration");
HistoricCaseInstance hci = historyService.createHistoricCaseInstanceQuery()
    .caseInstanceId(caseInstanceId).singleResult();
if (hci == null) throw new IllegalArgumentException("Unknown historic case instance: " + caseInstanceId);

Type guard

boolean isValidInstanceId(String id) { return id != null && !id.isBlank(); }

Try / catch

try {
    execute(new HistoricCaseInstanceMigrationCmd(caseInstanceId, doc, cfg));
} catch (FlowableException e) {
    if (e.getMessage().contains("case instance id")) {
        throw new IllegalArgumentException("Resolve the historic case instance id before migrating", e);
    }
    throw e;
}

Prevention

When it happens

Trigger: Calling new HistoricCaseInstanceMigrationCmd(null, migrationDocument, cmmnEngineConfiguration) — e.g. the instance id came from a query that returned no row, a UI selection that was never populated, or HistoricCaseInstanceQuery.singleResult() returned null.

Common situations: Migrating after a lookup on a wrong engine/datasource so the id resolved to null; passing the runtime (non-historic) variable that was never set; batch jobs iterating over an empty result list and defaulting the id to null.

Related errors

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