flowable/flowable-engine · error · FlowableException

Migration Activity mapping missing for activity definition…

Error message

Migration Activity mapping missing for activity definition Ids:'" + Arrays.toString(executionActivityIdsToMapExplicitly.toArray()) + "'

What it means

Final safety check after preparing change-state builders: lists all running activity ids that ended up with neither an auto mapping nor an explicit mapping (including MI parent fallback). The migration is rejected wholesale, listing every unmapped activity definition id in the message.

Solutions

Iterate the reported activity ids and add .addActivityMapping(oldId, newId) for each in the migration builder
Run validateMigrations first and fix all reported issues before calling migrate
Keep activity ids unchanged in new model versions where possible
Handle instances individually: terminate or complete branches that cannot be mapped before migrating

Example fix

// before
migrationBuilder.migrate(id); // error: mapping missing for ['taskB','taskC']
// after
migrationBuilder.addActivityMapping("taskB","taskB2").addActivityMapping("taskC","taskC2").migrate(id);

Defensive patterns

Strategy: validation

Validate before calling

ProcessInstanceMigrationValidationResult r =
    runtimeService.createProcessInstanceMigrationBuilder().migrateToProcessDefinition(targetDefId)
        .validateMigrations(instanceIds);
for (ValidationMessage m : r.getValidationMessages()) {
    // collect unmapped activity ids and add mappings
}

Try / catch

try {
    migrationBuilder.migrate(instanceId);
} catch (FlowableException e) {
    if (e.getMessage().startsWith("Migration Activity mapping missing for activity definition Ids")) {
        // extract id list, addActivityMapping for each, retry
    }
}

Prevention

Run validateMigrations for every batch before migrate()
Adopt id-stability policy for process definitions
Map every renamed/deleted activity explicitly in migration documents
Log and handle unmapped instances individually instead of failing the batch silently

When it happens

Trigger: Calling migrate() or validateMigrations on instances whose running activity set contains ids absent from the target model and absent from the migration document's activity mappings.

Common situations: New definition version renamed or deleted activities on active branches; partial mapping documents; parallel branches with renamed tasks; validating migrations of many instances where some fail mapping.

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

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

Appendix: source

Thrown at modules/flowable-engine/src/main/java/org/flowable/engine/impl/migration/ProcessInstanceMigrationManagerImpl.java:862

                        }
                    }
                    if (activityMapping.isToCallActivity()) {
                        mainProcessChangeActivityStateBuilder.moveActivityIdsToSubProcessInstanceActivityId(fromActivityIds, toActivityId,
                                activityMapping.getToCallActivityId(),
                                activityMapping.getCallActivityProcessDefinitionVersion(),
                                (SingleToActivityOptions<?>) activityMapping);
                    } else {
                        mainProcessChangeActivityStateBuilder.moveExecutionsToSingleActivityId(executionIds, toActivityId, (SingleToActivityOptions<?>) activityMapping);
                    }
                }
                
            } else {
                throw new FlowableException("Unknown Activity Mapping or not implemented yet!!!");
            }
        }

        if (!executionActivityIdsToMapExplicitly.isEmpty()) {
            throw new FlowableException("Migration Activity mapping missing for activity definition Ids:'" + Arrays.toString(executionActivityIdsToMapExplicitly.toArray()) + "'");
        }

        return changeActivityStateBuilders;
    }

    protected boolean isSameOrDefaultTenant(String processInstanceTenantId, String processDefinitionKey, 
            String processDefinitionTenantId, ProcessEngineConfigurationImpl processEngineConfiguration) {
        
        if (processInstanceTenantId != null && processDefinitionTenantId != null) {
            boolean tenantIdsEqual = processInstanceTenantId.equals(processDefinitionTenantId);
            if (!tenantIdsEqual && processEngineConfiguration.isFallbackToDefaultTenant() && processEngineConfiguration.getDefaultTenantProvider() != null) {
                return processDefinitionTenantId.equals(processEngineConfiguration.getDefaultTenantProvider().getDefaultTenant(processInstanceTenantId, ScopeTypes.BPMN, processDefinitionKey));
            }
            
            return tenantIdsEqual;
            
        } else if (processInstanceTenantId == null && processDefinitionTenantId == null) {
            return true;

View on GitHub (pinned to d6d39ce1c6)