flowable/flowable-engine · error · ActivitiIllegalArgumentException

Unsupported Primary key type for JPA-Entity:

Error message

Unsupported Primary key type for JPA-Entity: 

What it means

createId converts the stored string representation of a primary key back to the entity's id type. Only a fixed set of types (Long, Integer, String, Short, Double, Float, BigDecimal, BigInteger, UUID) is supported; anything else throws this error.

Source

Thrown at modules/flowable5-engine/src/main/java/org/activiti/engine/impl/variable/JPAEntityMappings.java:170

            return Integer.parseInt(string);
        } else if (type == Float.class || type == float.class) {
            return Float.parseFloat(string);
        } else if (type == Double.class || type == double.class) {
            return Double.parseDouble(string);
        } else if (type == Character.class || type == char.class) {
            return Character.valueOf(string.charAt(0));
        } else if (type == java.util.Date.class) {
            return new java.util.Date(Long.parseLong(string));
        } else if (type == java.sql.Date.class) {
            return new java.sql.Date(Long.parseLong(string));
        } else if (type == BigDecimal.class) {
            return new BigDecimal(string);
        } else if (type == BigInteger.class) {
            return new BigInteger(string);
        } else if (type == UUID.class) {
            return UUID.fromString(string);
        } else {
            throw new ActivitiIllegalArgumentException("Unsupported Primary key type for JPA-Entity: " + type.getName());
        }
    }

    public String getIdString(Object value) {
        if (value == null) {
            throw new ActivitiIllegalArgumentException("Value of primary key for JPA-Entity cannot be null");
        }
        // Only java.sql.date and java.util.date require custom handling, the other types
        // can just use toString()
        if (value instanceof java.util.Date) {
            return String.valueOf(((java.util.Date) value).getTime());
        } else if (value instanceof java.sql.Date) {
            return String.valueOf(((java.sql.Date) value).getTime());
        } else if (value instanceof Long || value instanceof String || value instanceof Byte
                || value instanceof Short || value instanceof Integer || value instanceof Float
                || value instanceof Double || value instanceof Character || value instanceof BigDecimal
                || value instanceof BigInteger
                || value instanceof UUID) {

View on GitHub (pinned to d6d39ce1c6)

Solutions

1. Change the @Id to a supported type (Long, String, UUID, etc.)
2. Add a surrogate numeric/string primary key and keep the business key as a normal column
3. Handle the id conversion yourself and store the id as a plain string/long variable instead of a JPA entity variable
4. Upgrade to an engine version whose JPA mapping supports the desired id type

Example fix

// before
@Entity public class Order { @Id private Date created; }
// after
@Entity public class Order { @Id private Long id; private Date created; }

Set<Class<?>> supported = Set.of(Long.class, Integer.class, String.class, Short.class,
    Double.class, Float.class, BigDecimal.class, BigInteger.class, UUID.class);
Field idField = findIdField(entityClass);
if (!supported.contains(idField.getType())) {
    throw new IllegalArgumentException("Unsupported id type: " + idField.getType());
}

boolean hasSupportedIdType(Class<?> entityClass) {
    return supportedIdTypes.contains(getIdFieldType(entityClass));
}

try {
    Object entity = mappings.getJPAEntity(className, idString);
} catch (ActivitiIllegalArgumentException e) {
    if (e.getMessage().startsWith("Unsupported Primary key type")) {
        // convert id manually or switch entity id to a supported type
    } else { throw e; }
}

When it happens

Trigger: An entity's @Id is of a type outside the supported list (e.g. java.util.Date, char, byte[], or a custom @Embeddable key class) and a JPA entity variable is stored or read.

Common situations: Composite/@EmbeddedId key classes; ids typed as Date or custom value objects; entities migrated to jakarta/javax types not covered by this legacy (flowable5) mapping code.

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

• Unsupported Primary key type for JPA-Entity: ${type}
• Variables containing a list of JPA entities cannot be used t
• Value of primary key for JPA-Entity cannot be null
• Cannot find field or method with annotation @Id on class '${
• Cannot get id from JPA Entity, no id method/field set

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