flowable/flowable-engine · error · FlowableIllegalArgumentException

Unsupported Primary key type for JPA-Entity: ${type}

Error message

Unsupported Primary key type for JPA-Entity: ${type}

What it means

Flowable's JPA variable support can only map JPA entity primary keys of a fixed set of Java types (String, Long, Integer, Float, Double, Byte, Short, Character, Boolean, BigDecimal, BigInteger, java.util.Date, UUID). When a JPA entity uses a primary key of any other type, createId throws this error instead of silently producing a wrong key string.

Source

Thrown at modules/flowable-variable-service/src/main/java/org/flowable/variable/service/impl/types/JPAEntityMappings.java:162

            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 FlowableIllegalArgumentException("Unsupported Primary key type for JPA-Entity: " + type.getName());
        }
    }

    public String getIdString(Object value) {
        if (value == null) {
            throw new FlowableIllegalArgumentException("Value of primary key for JPA-Entity cannot be null");
        }
        // Only java.util.Date requires 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 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) {
            return value.toString();
        } else {
            throw new FlowableIllegalArgumentException("Unsupported Primary key type for JPA-Entity: " + value.getClass().getName());
        }
    }

View on GitHub (pinned to d6d39ce1c6)

Solutions

1. Change the @Id field type of the JPA entity to one of the supported types (String, Long, Integer, UUID, BigDecimal, BigInteger, Date, etc.).
2. If a custom key class is required, store the entity's natural key in a separate supported-type field and use that as @Id (e.g. replace composite id with a String key).
3. Avoid storing/looking up that entity as a Flowable JPA variable; keep the reference yourself in a custom variable type.
4. If the type genuinely belongs in the supported set, verify no generic type erasure makes `type` resolve to Object.

Example fix

// before
@Id
private CompoundKey id; // custom class -> throws
// after
@Id
private String id; // supported type

private static final Set<Class<?>> SUPPORTED = Set.of(String.class, Long.class, Integer.class, Short.class, Byte.class, Float.class, Double.class, Character.class, Boolean.class, BigDecimal.class, BigInteger.class, java.util.Date.class, java.util.UUID.class);
if (!SUPPORTED.contains(entity.getClass().getMethod("getId").getReturnType())) throw new IllegalArgumentException(entity + " uses unsupported @Id type");

boolean hasSupportedId(Object e) { try { return SUPPORTED.contains(e.getClass().getMethod("getId").getReturnType()); } catch (Exception ex) { return false; } }

try { variables.put("entity", jpaEntity); } catch (FlowableIllegalArgumentException e) { if (e.getMessage().startsWith("Unsupported Primary key type")) { throw new ConfigurationException("Entity @Id type not supported by Flowable JPA variables"); } throw e; }

When it happens

Trigger: Calling createId (via primaryKey -> getJPAIdString) on an entity whose @Id field type is not in the supported set — e.g. a custom @Embeddable key class, char[] wrapper, or enum-typed @Id — during JPA variable lookups.

Common situations: Projects migrating from Hibernate-native composite/embedded ids to Flowable variables; entities using custom Serializable key classes; enum-annotated primary keys.

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

• Value of primary key for JPA-Entity cannot be null
• Unsupported Primary key type for JPA-Entity:
• Unsupported IO parameter type '
• unsupported variable scope type:
• Unrecognized ChannelModel class : ${channelModel.getClass()}

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