Issue with migrating the process instance due to event based subprocess

Camunda 8 Topics
1

Hi there,

I’m trying to migrate process instance from one version to another. In both, source and target process definition I have the same event-based subprocess with message start event (nothing has changed here).

Here is the code that I’m using for migration (Java/Spring Boot):

public void migrate(Long processInstanceKey,
                    Long targetProcessDefinitionKey,
                    List<Map<String, String>> mappings) {
  List<MappingInstruction> mappingInstructions = prepareMigrationInstructions(mappings);

  log.info("Mapping instructions {}", mappingInstructions);

  MigrationPlan migrationPlan = new MigrationPlanImpl(
      targetProcessDefinitionKey,
      mappingInstructions
  );

  zeebeClient.newMigrateProcessInstanceCommand(processInstanceKey)
      .migrationPlan(migrationPlan)
      .send()
      .join();
}

private List<MappingInstruction> prepareMigrationInstructions(List<Map<String, String>> mappings) {
  if (CollectionUtils.isEmpty(mappings)) return Collections.emptyList();

  return mappings.stream()
      .flatMap(instruction -> instruction.entrySet().stream()
          .map(entry -> new MappingInstruction(entry.getKey(), entry.getValue())))
      .toList();

}

And here are the mapping instructions that I’ve provided:

[
   {
      "CancelLoanApprovalMessageStartEvent": "CancelLoanApprovalMessageStartEvent"
   }
]

and the error I’m getting is the following:

o.grpc.StatusRuntimeException: INVALID_ARGUMENT: Command 'MIGRATE' rejected with code 'INVALID_ARGUMENT': Expected to migrate process instance '2251799836840085' but mapping instructions contain a non-existing source element id 'CancelLoanApprovalMessageStartEvent'. Elements provided in mapping instructions must exist in the source process definition.

Any idea what can be the issue and how to solve it?

I’m using Camunda 8.6.11 Self-Managed.

2

Hi @heril.muratovic06,

The issue you’re encountering is related to how process instance migration handles event-based subprocesses and their message start events. The error indicates that the migration engine cannot find the source element ID CancelLoanApprovalMessageStartEvent in your current process instance’s process definition.

Root Cause

Based on the error and your description, this is likely happening because:

  1. The event-based subprocess with the message start event doesn’t currently exist in the running process instance - even though you mentioned both versions have the same event-based subprocess, the migration engine is treating this as a new element being added to the target process definition.

  2. You’re providing a mapping instruction for an element that should be automatically handled - When migrating to a process definition that adds new catch events (like message start events in event subprocesses), you should not include mapping instructions for these new events.

Solution

Remove the mapping instruction for the message start event. According to the Camunda documentation on process instance migration:

When adding new catch events (like a message start event in an event subprocess), you do not need to provide a mapping for the new event. You only map existing active elements. The migration engine will automatically open a new subscription for the new catch event after migration.

Try running your migration with an empty mappings list:

// Instead of providing the mapping instruction, use an empty list
migrate(processInstanceKey, targetProcessDefinitionKey, Collections.emptyList());

Or if you have other elements that need mapping, simply remove the CancelLoanApprovalMessageStartEvent mapping:

[
   // Remove this mapping instruction
   // {
   //    "CancelLoanApprovalMessageStartEvent": "CancelLoanApprovalMessageStartEvent"
   // }
]

Key Points

  • Only map existing active elements in your process instance that need to be migrated to different elements in the target process definition
  • New catch events are handled automatically - the migration engine will create new subscriptions for them
  • Source element IDs must exist in the current process instance’s process definition, not just in the target definition

Verification Steps

  1. Check your current process instance to see if the event-based subprocess is actually active/instantiated
  2. If you need to map other elements, ensure they exist in the source process definition
  3. Let the migration engine handle the new event subscriptions automatically

For more details, see the official documentation on process instance migration limitations and the Zeebe API reference.

Let me know if this resolves your issue or if you need further clarification!

3

Hi there,

this is the error message I’m getting after removing the instructions, actually after providing the empty list:

io.grpc.StatusRuntimeException: FAILED_PRECONDITION: Command 'MIGRATE' rejected with code 'INVALID_STATE': 
Expected to migrate process instance '2251799836840085' but 
active element with id 'LoanApprovalProcess' attempts to subscribe 
to a message it is already subscribed to with name 'CancelLoanApprovalMessage'. Migrating active elements that subscribe to a message they 
are already subscribed to is not possible yet. 
Please provide a mapping instruction to message catch event with id 'CancelLoanApprovalMessageStartEvent' to migrate the respective message subscription.
4

Thanks for the additional information! This error reveals the actual issue. The problem is that your process instance is already subscribed to the CancelLoanApprovalMessage and the migration is trying to create a duplicate subscription.

Understanding the Issue

The error message is telling us:

  • Your process instance (with active element LoanApprovalProcess) is already subscribed to the message CancelLoanApprovalMessage
  • The migration is attempting to create another subscription to the same message
  • This would result in duplicate subscriptions, which is not allowed

The Solution

You need to provide a mapping instruction to properly migrate the existing message subscription. The error message actually gives us the hint:

Please provide a mapping instruction to message catch event with id ‘CancelLoanApprovalMessageStartEvent’ to migrate the respective message subscription.

So your original mapping instruction was correct, but you need to ensure you’re mapping from the existing message catch event in your source process to the corresponding one in the target process.

Try this approach:

// Use your original mapping instruction
List<Map<String, String>> mappings = List.of(
    Map.of("CancelLoanApprovalMessageStartEvent", "CancelLoanApprovalMessageStartEvent")
);

migrate(processInstanceKey, targetProcessDefinitionKey, mappings);

Troubleshooting Steps

If you still get the “non-existing source element id” error, you need to:

  1. Verify the actual element ID in your source process definition:

    • Open your source process definition in Camunda Modeler
    • Select the message start event in the event-based subprocess
    • Check the exact ID in the properties panel
    • The ID might be different from what you expect

  2. Check if the event subprocess is actually active:

    • The event-based subprocess with the message start event must be active in your process instance for the mapping to work
    • If it’s not active, you might need a different approach

  3. Use the correct source element ID:

    • Make sure you’re using the exact ID from the source process definition
    • Element IDs are case-sensitive

Alternative Approach

If the element ID issue persists, you can:

  1. Export your source process definition and check the BPMN XML for the exact element ID
  2. Use Operate or Zeebe API to inspect the active elements in your process instance
  3. Verify both process definitions have the same message name and element structure

The key insight here is that when you have an existing message subscription that needs to be migrated (not added new), you must provide a mapping instruction to properly transfer the subscription from source to target.

Let me know what element ID you find in your source process definition, and we can troubleshoot further if needed!

5

The issue here was indeed the identifier of the element in the source process definition. It was somehow automatically changed by the technical ids plugin that I’m using in the Camunda Modeler.

6

This topic was automatically closed 7 days after the last reply. New replies are no longer allowed.