Resolving Correlation Key Errors in jBPM

[error_1.61]

This guide covers the complete fix for correlation key issues in jBPM, especially those caused by key length limitations or incorrect configurations. These issues typically surface when starting or signaling a process using a business key or correlation key.

---

Common Error Messages

• “Process instance with correlation key already exists”
• “Could not find process instance with correlation key”
• “Correlation key is null or malformed”

---

Root Causes

Cause	Description
Duplicate Correlation Keys	Attempting to start a new process instance with an already-used key.
Improper Key Construction	Not using the CorrelationKeyFactory or passing a malformed/null key.
Inconsistent Generation	Different parts of the system generate keys differently.
Invalid Lookup	Signaling or retrieving a process with a key that doesn’t exist.
DB Truncation	Long keys are being silently truncated by the database due to column length limits.

---

Solution

NOTE: Assuming the desired length of correlation key is 4096

Part 1: Update Database Schema

Increase the length of correlation key–related columns in your database. Default is often 255 characters, which is not enough for long or composite keys.

SQL Example

ALTER TABLE <BPM_DB_SCHEMA_NAME>.correlationkeyinfo
ALTER COLUMN "name" TYPE character varying(4096);

ALTER TABLE <BPM_DB_SCHEMA_NAME>.correlationpropertyinfo
ALTER COLUMN "name" TYPE character varying(4096);
ALTER TABLE <BPM_DB_SCHEMA_NAME>.correlationpropertyinfo
ALTER COLUMN "value" TYPE character varying(4096);

ALTER TABLE <BPM_DB_SCHEMA_NAME>.nodeinstancelog
ALTER COLUMN "connection" TYPE character varying(4096);
ALTER TABLE <BPM_DB_SCHEMA_NAME>.nodeinstancelog
ALTER COLUMN "nodeid" TYPE character varying(4096);

ALTER TABLE <BPM_DB_SCHEMA_NAME>.processinstancelog
ALTER COLUMN "correlationkey" TYPE character varying(4096);

ALTER TABLE <BPM_DB_SCHEMA_NAME>.taskevent
ALTER COLUMN "correlationkey" TYPE character varying(4096);

---

Part 2: Update persistence.xml

To align JPA/Hibernate mappings with the updated DB schema, register the correct classes and set length properties.

Add these classes:

<class>org.jbpm.persistence.api.PersistentCorrelationKey</class>
<class>org.jbpm.persistence.correlation.CorrelationKeyInfo</class>

Set correlation key length properties:

<property name="org.jbpm.correlationkey.length" value="4096"/>
<property name="org.jbpm.persistence.correlation.CorrelationKeyInfo.CORRELATION_KEY_LOG_LENGTH" value="4096"/>

Where to set this:

• Navigate to the settings tab while configuring your project.
• Switch to Persistence configuration and add the properties as shown below
  
  

---

Part 3: Set JVM Parameters

During deployment, you need to pass the correlation key length settings as system properties via JAVA_OPTS.

Add this to your environment:

export JAVA_OPTS="$JAVA_OPTS -Dorg.jbpm.persistence.correlation.CorrelationKeyInfo.CORRELATION_KEY_LOG_LENGTH=4096 -Dorg.jbpm.correlationkey.length=4096"

Avoid repeating the same -Dorg.jbpm.correlationkey.length property multiple times. Once is enough.

Where to set this:

Environment	How to configure
Standalone JVM	Set in shell or startup script
WildFly / JBoss	Edit standalone.conf or domain.conf
Docker	Use ENV JAVA_OPTS=… in Dockerfile
Kubernetes	Use env in your container spec

---

Validation Checklist

• Database schema updated (varchar 4096 on all related fields)
• persistence.xml updated with correlation key classes and length properties
• JAVA_OPTS includes required -D flags
• End-to-end test done using a long correlation key (acheived when the depth of parent-child hierarchy in process is more than 5)
• Logs confirmed that no truncation or lookup failures occur

---