Why does modifying the source collection while streaming it cause a ConcurrentModificationException, and how do you restructure to avoid it?

## Terms - **Source collection**: the `List`, `Set`, `Map` (etc.) a stream is created from via `.stream()`. - **Lazy traversal**: the stream doesn't copy elements up front; when the **terminal** operation runs, it walks the source through a **spliterator** (the stream-era cousin of an iterator) pulling elements on demand. - **Structural modification**: adding or removing elements (changing the size/structure), as opposed to merely updating a field of an element already present. - **Fail-fast**: a collection that *detects* structural modification during iteration and throws immediately, rather than risking corrupted or undefined results. - **`modCount`**: an internal counter most JDK collections bump on every structural change. The iterator/spliterator remembers the expected value and compares; a mismatch → `ConcurrentModificationException` (CME). ## Why the exception happens Because traversal is lazy and reads the live source, changing that source mid-stream breaks the iterator's assumptions: ```java List<Integer> list = new ArrayList<>(List.of(1, 2, 3, 4)); list.stream().forEach(x -> { if (x == 2) list.remove(Integer.valueOf(2)); // structural change DURING traversal }); // throws java.util.ConcurrentModificationException ``` The `remove` bumps `modCount`; the spliterator notices on its next step and throws. The name is misleading: **"concurrent" means concurrent with the iteration**, even in a single thread. It's a *best-effort* safety net, not a guarantee — fail-fast behavior is documented as not to be relied on for correctness, only as a debugging aid. The same happens if a *different* method, or another thread, mutates the collection while your stream is being consumed. ## What does NOT trigger it Mutating a **field of an existing element** is not a structural change and won't throw: ```java people.stream().forEach(p -> p.setActive(false)); // OK structurally (but see side-effect cautions) ``` The pitfall is specifically **add/remove on the source** during traversal. ## How to restructure ### 1. Produce a new collection (the functional way) Don't edit the source while reading it — build the result and replace: ```java List<Integer> kept = list.stream() .filter(x -> x != 2) .collect(Collectors.toList()); // new list, source untouched during traversal ``` ### 2. Use in-place collection APIs designed for it For removal, `removeIf` mutates safely because it manages its own iteration: ```java list.removeIf(x -> x == 2); // no CME, in-place ``` For map values, `replaceAll`/`compute` do controlled in-place updates. ### 3. Use a CME-immune collection when you truly need concurrent mutation Collections like `CopyOnWriteArrayList` or `ConcurrentHashMap` have **weakly consistent** spliterators that tolerate modification during traversal (they won't throw CME) — at the cost of weaker visibility (you may or may not see concurrent changes) and, for copy-on-write, expensive writes. Choose these deliberately for genuine concurrency, not to paper over a single-threaded design mistake. ## Mental model A stream is a **reader** of the source. Don't rewrite a book while you're reading it. Either read it to produce a *new* book (`collect`), or use a tool built to edit in place (`removeIf`).