flowable/flowable-engine · error · FlowableException

Process definition key cannot be null

Error message

Process definition key cannot be null

What it means

ProcessInstanceMigrationDocumentBuilderImpl.build() validates the migration document before creating it. If no target process definition ID was set, a target process definition key is mandatory to identify the destination process definition; building without either throws this FlowableException.

Solutions

1. Call migrateToProcessDefinitionKey(...) on the builder before build()
2. Or call migrateToProcessDefinitionId(...) / migrateToProcessDefinition(version, key) so the ID is set
3. If building from JSON, ensure the migration document contains the target process definition key

Example fix

// before
ProcessInstanceMigrationDocument doc = processEngine.getRuntimeService()
    .createProcessInstanceMigrationBuilder().build();
// after
ProcessInstanceMigrationDocument doc = processEngine.getRuntimeService()
    .createProcessInstanceMigrationBuilder()
    .migrateToProcessDefinitionKey("newOrderProcess")
    .build();

if (targetKey == null && targetId == null) {
    throw new IllegalArgumentException("Provide migrateToProcessDefinitionKey or Id before build()");
}

try {
    document = builder.build();
} catch (FlowableException e) {
    if (e.getMessage().contains("Process definition key cannot be null")) {
        builder.migrateToProcessDefinitionKey(defaultKey);
        document = builder.build();
    } else { throw e; }
}

When it happens

Trigger: Calling build() on a migration document builder where migrateToProcessDefinitionId is null and neither migrateToProcessDefinitionKey nor any per-process-definition key was set (e.g. createProcessInstanceMigrationBuilder() used without calling migrateToProcessDefinition(Key)).

Common situations: Forgetting to call migrateToProcessDefinition(...) before build(); building the document from JSON where the target key field is missing; refactoring that removed the target definition call.

Understand the failure class

Background: "missing required argument" and "the following required arguments were not provided": what required-argument errors mean and how to fix them — this error's family across 20 libraries.

Related errors

• Cannot validate process migration, not enough information
• Must specify a process definition id to migrate
• Must specify a process instance id to migrate
• Must specify a process migration document to migrate
• Process definition version must be a positive number

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

Appendix: source

Thrown at modules/flowable-engine/src/main/java/org/flowable/engine/impl/migration/ProcessInstanceMigrationDocumentBuilderImpl.java:153

    @Override
    public ProcessInstanceMigrationDocumentBuilder addProcessInstanceVariable(String variableName, Object variableValue) {
        this.processInstanceVariables.put(variableName, variableValue);
        return this;
    }

    @Override
    public ProcessInstanceMigrationDocumentBuilder addProcessInstanceVariables(Map<String, Object> processInstanceVariables) {
        this.processInstanceVariables.putAll(processInstanceVariables);
        return this;
    }

    @Override
    public ProcessInstanceMigrationDocument build() {

        if (migrateToProcessDefinitionId == null) {
            if (migrateToProcessDefinitionKey == null) {
                throw new FlowableException("Process definition key cannot be null");
            }
            if (migrateToProcessDefinitionVersion != null && migrateToProcessDefinitionVersion < 0) {
                throw new FlowableException("Process definition version must be a positive number");
            }
        }

        ProcessInstanceMigrationDocumentImpl document = new ProcessInstanceMigrationDocumentImpl();
        document.setProcessInstanceIdsToMigrate(processInstanceIdsToMigrate);
        document.setMigrateToProcessDefinitionId(migrateToProcessDefinitionId);
        document.setMigrateToProcessDefinition(migrateToProcessDefinitionKey, migrateToProcessDefinitionVersion, migrateToProcessDefinitionTenantId);
        if (preUpgradeScript != null) {
            document.setPreUpgradeScript(preUpgradeScript);
        }
        if (preUpgradeJavaDelegate != null) {
            document.setPreUpgradeJavaDelegate(preUpgradeJavaDelegate);
        }
        if (preUpgradeJavaDelegateExpression != null) {
            document.setPreUpgradeJavaDelegateExpression(preUpgradeJavaDelegateExpression);

View on GitHub (pinned to d6d39ce1c6)