{"record":{"id":"1d5fbc8ece81e9fe","repo":"flowable/flowable-engine","slug":"unknown-activity-mapping-or-not-implemented-yet","errorCode":null,"errorMessage":"Unknown Activity Mapping or not implemented yet!!!","messagePattern":"Unknown Activity Mapping or not implemented yet!!!","errorType":"exception","errorClass":"FlowableException","httpStatus":null,"severity":"error","filePath":"modules/flowable-engine/src/main/java/org/flowable/engine/impl/migration/ProcessInstanceMigrationManagerImpl.java","lineNumber":857,"sourceCode":"                    for (String activityId : fromActivityIds) {\n                        if (executionActivityIdsToMapExplicitly.contains(activityId)) {\n                            List<ExecutionEntity> executionEntities = filteredExecutionsByActivityId.get(activityId);\n                            executionIds.addAll(executionEntities.stream().map(ExecutionEntity::getId).collect(Collectors.toList()));\n                            executionActivityIdsToMapExplicitly.remove(activityId);\n                        }\n                    }\n                    if (activityMapping.isToCallActivity()) {\n                        mainProcessChangeActivityStateBuilder.moveActivityIdsToSubProcessInstanceActivityId(fromActivityIds, toActivityId,\n                                activityMapping.getToCallActivityId(),\n                                activityMapping.getCallActivityProcessDefinitionVersion(),\n                                (SingleToActivityOptions<?>) activityMapping);\n                    } else {\n                        mainProcessChangeActivityStateBuilder.moveExecutionsToSingleActivityId(executionIds, toActivityId, (SingleToActivityOptions<?>) activityMapping);\n                    }\n                }\n                \n            } else {\n                throw new FlowableException(\"Unknown Activity Mapping or not implemented yet!!!\");\n            }\n        }\n\n        if (!executionActivityIdsToMapExplicitly.isEmpty()) {\n            throw new FlowableException(\"Migration Activity mapping missing for activity definition Ids:'\" + Arrays.toString(executionActivityIdsToMapExplicitly.toArray()) + \"'\");\n        }\n\n        return changeActivityStateBuilders;\n    }\n\n    protected boolean isSameOrDefaultTenant(String processInstanceTenantId, String processDefinitionKey, \n            String processDefinitionTenantId, ProcessEngineConfigurationImpl processEngineConfiguration) {\n        \n        if (processInstanceTenantId != null && processDefinitionTenantId != null) {\n            boolean tenantIdsEqual = processInstanceTenantId.equals(processDefinitionTenantId);\n            if (!tenantIdsEqual && processEngineConfiguration.isFallbackToDefaultTenant() && processEngineConfiguration.getDefaultTenantProvider() != null) {\n                return processDefinitionTenantId.equals(processEngineConfiguration.getDefaultTenantProvider().getDefaultTenant(processInstanceTenantId, ScopeTypes.BPMN, processDefinitionKey));\n            }","sourceCodeStart":839,"sourceCodeEnd":875,"githubUrl":"https://github.com/flowable/flowable-engine/blob/d6d39ce1c69ff244f2d9dc6af756a9b95e865586/modules/flowable-engine/src/main/java/org/flowable/engine/impl/migration/ProcessInstanceMigrationManagerImpl.java#L839-L875","documentation":"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.","triggerScenarios":"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.","commonSituations":"Mixing Flowable engine versions between document creation and application; custom migration document manipulation; engine bug where a mapping subtype is not handled.","solutions":["Rebuild the migration document with the same Flowable version that applies it","Upgrade/align the flowable-engine dependency across services that create and apply migration documents","Inspect the document's activity mappings and recreate only supported mappings (processInstanceMigrationDocumentConverter output)","Report to Flowable if a supported mapping type triggers this; check the engine branch handling mapping types"],"exampleFix":"// before\n// document created with Flowable 6.8 mappings applied on 6.7 engine\n// after\n// align both sides on Flowable 6.8, rebuild: runtimeService.createProcessInstanceMigrationBuilder()...buildProcessInstanceMigrationDocument()","handlingStrategy":"try-catch","validationCode":"// ensure document and engine versions match\nString engineVersion = ProcessEngine.VERSION;\n// rebuild the document with the same version that applies it","typeGuard":null,"tryCatchPattern":"try {\n    migrationDocumentProcessor.runProcessInstanceMigration(document, instanceId);\n} catch (FlowableException e) {\n    if (e.getMessage().contains(\"Unknown Activity Mapping\")) {\n        // rebuild document with current engine version and retry\n    }\n}","preventionTips":["Pin flowable-engine to one version across all services","Never hand-edit serialized migration documents","Rebuild migration documents at migration time instead of storing them long-term","Track Flowable release notes for mapping type changes"],"tags":["flowable","migration","internal","version-mismatch"],"backgroundTag":"internal-invariant-violation","analyzedSha":"d6d39ce1c69ff244f2d9dc6af756a9b95e865586","analyzedAt":"2026-09-11T06:41:19.413Z","contentChangedAt":"2026-09-11T06:41:19.413Z","schemaVersion":2},"datasetVersion":"2026-09-18T11:17:12.947Z"}