Why BeanUtils.copyProperties Causes ClassCastException and How to Fix It

Background

During an agile team project, a unit test triggered a

java.lang.ClassCastException

because a service interface returned a

java.util.HashMap

that could not be cast to the expected

BatchInfo

class.

Investigation Process

The team first suspected the request payload format and used testing tools and local debugging to verify the payload, which succeeded. Next they examined the serialization method and recent code changes, focusing on a suspicious line:

<code>private List&lt;CargoInfo&gt; convertToCargoInfo(OutboundEventCallbackRequest outboundEventCallbackRequest) {
    return outboundEventCallbackRequest.getCargos().stream().map(item -> {
        CargoInfo cargoInfo = new CargoInfo();
        BeanUtils.copyProperties(item, cargoInfo);
        return cargoInfo;
    }).collect(Collectors.toList());
}</code>

The root cause was that

BeanUtils.copyProperties

performs a shallow copy, copying only reference fields. During deserialization the framework could not locate the target class and converted the object to a

Map

, leading to the

ClassCastException

.

An additional diagram visualizes the shallow‑copy problem.

Solution and Reflections

Removing

BeanUtils.copyProperties

and assigning fields manually resolved the issue. The team reflected that shallow‑copy utilities can be risky and recommended using a dedicated mapper such as MapStruct for complex conversions.