flowable/flowable-engine · error · FlowableException

Unknown Activity Mapping or not implemented yet!!!

Error message

Unknown Activity Mapping or not implemented yet!!!

What it means

Internal guard in prepareChangeStateBuilders: the processed activity mapping object type was not one of the supported options (e.g. SingleToActivityOptions variants). Indicates a migration document containing an unrecognized activity mapping implementation, or an engine version where that mapping type is not implemented.

Solutions

  1. Rebuild the migration document with the same Flowable version that applies it
  2. Upgrade/align the flowable-engine dependency across services that create and apply migration documents
  3. Inspect the document's activity mappings and recreate only supported mappings (processInstanceMigrationDocumentConverter output)
  4. Report to Flowable if a supported mapping type triggers this; check the engine branch handling mapping types

Example fix

// before
// document created with Flowable 6.8 mappings applied on 6.7 engine
// after
// align both sides on Flowable 6.8, rebuild: runtimeService.createProcessInstanceMigrationBuilder()...buildProcessInstanceMigrationDocument()
Defensive patterns

Strategy: try-catch

Validate before calling

// ensure document and engine versions match
String engineVersion = ProcessEngine.VERSION;
// rebuild the document with the same version that applies it

Try / catch

try {
    migrationDocumentProcessor.runProcessInstanceMigration(document, instanceId);
} catch (FlowableException e) {
    if (e.getMessage().contains("Unknown Activity Mapping")) {
        // rebuild document with current engine version and retry
    }
}

Prevention

When it happens

Trigger: Applying a migration document whose activity mapping entry is of an unexpected/unimplemented type, e.g. built by a different Flowable version or manually constructed mapping object.

Common situations: Mixing Flowable engine versions between document creation and application; custom migration document manipulation; engine bug where a mapping subtype is not handled.

Understand the failure class

Background: "This is a bug, please report it": internal invariant violations, unreachable panics, and SNH errors explained — this error's family across 47 libraries.

Related errors

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

Appendix: source

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

                    for (String activityId : fromActivityIds) {
                        if (executionActivityIdsToMapExplicitly.contains(activityId)) {
                            List<ExecutionEntity> executionEntities = filteredExecutionsByActivityId.get(activityId);
                            executionIds.addAll(executionEntities.stream().map(ExecutionEntity::getId).collect(Collectors.toList()));
                            executionActivityIdsToMapExplicitly.remove(activityId);
                        }
                    }
                    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));
            }

View on GitHub (pinned to d6d39ce1c6)