flowable/flowable-engine · error · FlowableException

Unexpected exception when deserializing JPA id's

Error message

Unexpected exception when deserializing JPA id's

What it means

Companion to [4045]: after successfully deserializing, if the object is a String[] it is returned; if readObject itself throws IOException or ClassNotFoundException, Flowable rethrows this FlowableException ('Unexpected exception when deserializing JPA id's').

Solutions

1. Check the wrapped cause: ClassNotFoundException means missing class on classpath — restore the class or migrate data
2. IOException usually means corrupt/truncated bytes — re-set the variable or fix the stored bytes
3. Use BLOB-safe transport for variable bytes (don't route binary data through text columns)
4. Pin serialization-compatible classes across cluster nodes

Example fix

// before
// class refactor removed com.acme.CustomId used in old variables
// after
// keep a serializable legacy class or run a migration that rewrites variables to String ids

// ensure the serialized classes exist on this node's classpath
try { Class.forName("com.acme.CustomId"); } catch (ClassNotFoundException e) { /* restore or migrate */ }

try { Object v = runtimeService.getVariable(executionId, "customers"); } catch (FlowableException e) { if (e.getMessage().contains("deserializing JPA id")) { Throwable c = e.getCause(); if (c instanceof ClassNotFoundException) { log.error("Missing class for stored variable", c); } else { log.error("Corrupt variable bytes", c); } } throw e; }

When it happens

Trigger: deserializeIds called from ids() during getValue where ObjectInputStream.readObject fails — truncated/garbled byte array, or the serialized class cannot be found on the classpath (serialization of non-String objects in a customized build).

Common situations: Partial DB writes leaving truncated bytes; classpath differences between write and read nodes (custom ID classes removed during refactor); DB charset/encoding mishandling of binary columns.

Related errors

• Deserialized value is not an array of ID's:
• BPMN XSD could not be found
• Cannot flush EntityManager, an active transaction is…
• Cannot read default EL properties
• Cannot set JPA variable:

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

Appendix: source

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

            return baos.toByteArray();
        } catch (IOException ioe) {
            throw new FlowableException("Unexpected exception when serializing JPA id's", ioe);
        }
    }

    protected String[] deserializeIds(byte[] bytes) {
        try {
            ByteArrayInputStream bais = new ByteArrayInputStream(bytes);
            ObjectInputStream in = new ObjectInputStream(bais);

            Object read = in.readObject();
            if (!(read instanceof String[])) {
                throw new FlowableIllegalArgumentException("Deserialized value is not an array of ID's: " + read);
            }

            return (String[]) read;
        } catch (IOException | ClassNotFoundException ioe) {
            throw new FlowableException("Unexpected exception when deserializing JPA id's", ioe);
        }
    }

}

View on GitHub (pinned to d6d39ce1c6)