flowable/flowable-engine · error · FlowableException

Cannot convert mapping of type

Error message

Cannot convert mapping of type '${mapping.getClass()}'

What it means

Thrown during conversion of a ProcessInstanceMigrationDocument to JSON when an ActivityMigrationMapping subclass has no registered converter in activityMigrationMappingConverters. Flowable only knows how to serialize mapping types it registered; unknown mapping types cannot be converted.

Solutions

  1. Use only standard mapping types created via ProcessInstanceMigrationBuilder / ActivityMigrationMappingOptions.
  2. If a custom mapping type is required, register a matching BaseActivityMigrationMappingConverter subclass in activityMigrationMappingConverters before serializing.
  3. Log and inspect mapping.getClass() to identify the unregistered type.
  4. Check that the Flowable version producing the mappings matches the version doing the conversion.

Example fix

// before
mappings.add(new MyCustomMapping("fromAct", "toAct"));
converter.convertToMigrationDocument(document); // throws

// after
mappings.add(ActivityMigrationMappingOptions.forName("fromAct").mapTo("toAct")); // standard supported mapping
Defensive patterns

Strategy: validation

Validate before calling

if (!ProcessInstanceMigrationDocumentConverter.isActivityMappingSupported(mapping.getClass())) { throw new IllegalArgumentException("Unsupported mapping type: " + mapping.getClass()); }

Prevention

When it happens

Trigger: Calling convertToJsonActivityMigrationMappings (via mappingNodes) with a List of ActivityMigrationMapping whose concrete class is not in the converter map — typically a custom ActivityMigrationMapping subclass added by user code.

Common situations: Extending the migration DSL with a custom mapping type and forgetting to register a converter; a Flowable upgrade introducing new mapping types used with an older converter map; passing the wrong mapping list to the serializer.

Understand the failure class

Background: UnsupportedOperationException and "is not supported" errors: when a library deliberately refuses a call — this error's family across 30 libraries.

Related errors

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

Appendix: source

Thrown at modules/flowable-engine/src/main/java/org/flowable/engine/migration/ProcessInstanceMigrationDocumentConverter.java:151

    }

    public static String convertToJsonString(ProcessInstanceMigrationDocument processInstanceMigrationDocument) {
        JsonNode jsonNode = convertToJson(processInstanceMigrationDocument);
        ObjectWriter objectWriter = objectMapper.writerWithDefaultPrettyPrinter();
        try {
            return objectWriter.writeValueAsString(jsonNode);
        } catch (JacksonException e) {
            return jsonNode.toString();
        }
    }

    protected static ArrayNode convertToJsonActivityMigrationMappings(List<? extends ActivityMigrationMapping> activityMigrationMappings) {
        ArrayNode mappingsArray = objectMapper.createArrayNode();

        for (ActivityMigrationMapping mapping : activityMigrationMappings) {
            BaseActivityMigrationMappingConverter mappingConverter = activityMigrationMappingConverters.get(mapping.getClass());
            if (mappingConverter == null) {
                throw new FlowableException("Cannot convert mapping of type '" + mapping.getClass() + "'");
            }
            ObjectNode mappingNode = mappingConverter.convertToJson(mapping, objectMapper);
            mappingsArray.add(mappingNode);
        }

        return mappingsArray;
    }
    
    protected static ArrayNode convertToJsonEnableActivityMappings(List<? extends EnableActivityMapping> enableActivityMappings) {
        ArrayNode mappingsArray = objectMapper.createArrayNode();

        for (EnableActivityMapping mapping : enableActivityMappings) {
            ObjectNode mappingNode = mappingsArray.addObject();
            mappingNode.put(ProcessInstanceMigrationDocumentConstants.ACTIVITY_ID_JSON_PROPERTY, mapping.getActivityId());
        }

        return mappingsArray;
    }

View on GitHub (pinned to d6d39ce1c6)