Why You Should Avoid Collectors.toMap in Java Streams

Java 8 introduced the Stream API, making it easy to collect results with collect(Collectors.toList()) or collect(Collectors.toSet()). Many developers naturally reach for collect(Collectors.toMap(...)) when they need a Map from a stream.

Given a simple User class with int id and String name, the author first writes:

public class UserTest {
    @Test
    public void demo() {
        List<User> userList = new ArrayList<>();
        // mock data
        userList.add(new User(1, "Alex"));
        userList.add(new User(1, "Beth"));
        Map<Integer, String> map = userList.stream()
            .collect(Collectors.toMap(User::getId, User::getName));
        System.out.println(map);
    }
}

Running this code throws an IllegalStateException because the two users share the same id (key = 1). The default toMap implementation treats duplicate keys as an error instead of overwriting them.

To resolve the duplicate‑key problem, the author adds a merge function that prefers the newer value:

Map<Integer, String> map = userList.stream()
    .collect(Collectors.toMap(User::getId, User::getName,
        (oldData, newData) -> newData));

This eliminates the exception, but a second run now fails with a NullPointerException because one entry has a null name. The merge function receives a null value, which is dereferenced.

To guard against null values, the author wraps the name extraction in Optional:

Map<Integer, String> map = userList.stream()
    .collect(Collectors.toMap(
        User::getId,
        it -> Optional.ofNullable(it.getName()).orElse(""),
        (oldData, newData) -> newData));

Now the stream produces a map where duplicate keys are merged and null names become empty strings, yielding the expected output.

For comparison, the author also shows a classic imperative solution using a for loop and a plain HashMap:

Map<Integer, String> map = new HashMap<>();
userList.forEach(it -> {
    map.put(it.getId(), it.getName());
});

While this loop avoids the pitfalls of toMap, it sacrifices the declarative style of streams. The article concludes that streams remain elegant, but Collectors.toMap must be used with explicit duplicate‑key handling and null‑value protection, otherwise falling back to an explicit loop is safer.