With .NET's Dictionary<TKey,TValue>, why can a foreach remove entries without an exception while adding one throws InvalidOperationException?
answer
- a counter the enumerator snapshots
- checked by the next MoveNext
- which operations bump the counter
- removal frees a slot, nothing moves
basics
~20 sEnumerators snapshot the collection's version and MoveNext throws InvalidOperationException when it changed. Since .NET Core 3.0 Dictionary's Remove and Clear no longer bump the version, because removal frees a slot without moving entries; adding a key still does.
solid answer
~40 sCollections like `List<T>` and `Dictionary<TKey,TValue>` keep a private version counter; `GetEnumerator()` snapshots it, and `MoveNext()` throws `InvalidOperationException` ("Collection was modified; enumeration operation may not execute.") when the two differ. The check fires on the next `MoveNext()`, not at the change, so a change followed by `break` passes. Since .NET Core 3.0, `Dictionary<TKey,TValue>.Remove` and `Clear` leave the version alone: removal marks the entry free without moving any other, so the enumerator's index stays valid. Adding a key can resize or reuse a slot behind the cursor, so it bumps the version. In .NET 10 overwriting an existing key's value and `HashSet<T>.Remove` don't bump it either. It is a same-thread safeguard, not thread safety.
code
csharp · 29 linesvar lastSeen = new Dictionary<string, int> { ["cpu"] = 91, ["disk"] = 40, ["net"] = 77 };
foreach (var (name, value) in lastSeen)
{
if (value < 50) lastSeen.Remove(name); // Remove does not bump the version
else lastSeen[name] = value + 1; // overwriting an existing key does not either
}
Console.WriteLine(string.Join(", ", lastSeen.OrderBy(p => p.Key))); // [cpu, 92], [net, 78]
try
{
foreach (var name in lastSeen.Keys)
lastSeen.TryAdd(name + "-peak", 0); // adding a key bumps the version
}
catch (InvalidOperationException ex)
{
Console.WriteLine($"{ex.GetType().Name}: {ex.Message}");
}
var points = new List<int> { 1, 2, 3 };
try
{
foreach (int x in points)
if (x == 3) points.Add(4); // change made on the LAST element
}
catch (InvalidOperationException)
{
Console.WriteLine("List<int>: thrown by the MoveNext after the last element");
}go deeper
Remember that changing a collection inside its own foreach usually makes the loop throw InvalidOperationException, and that Dictionary is the notable type that allows Remove.
Explain the version counter: snapshot at GetEnumerator, compared in MoveNext, so the exception comes from the next MoveNext rather than from the change itself.
Explain why Dictionary removal is safe (entries do not move, freed slots are skipped) while adds are not, name the release that changed it, and separate this check from thread safety.
Decide whether code may rely on remove-during-enumeration: it is tied to specific types and releases, so a shared library that might run on .NET Framework or swap collection types should not.
## The version counter behind the exception Most mutable collections in `System.Collections.Generic` carry a private `int _version` field. The rule is simple: - every operation that could invalidate an enumerator's position **increments** `_version`; - an enumerator copies `_version` when it is created by `GetEnumerator()`; - the enumerator's `MoveNext()` (and its `IEnumerator.Reset()`) compares the two and, if they differ, throws **`InvalidOperationException`** with the message "Collection was modified; enumeration operation may not execute." Three consequences follow from where the check sits: 1. The exception is raised by the **next `MoveNext()`**, not by the method that changed the collection. The `Add` or `Remove` call succeeds; the loop fails when it asks for the next element. 2. A change made while processing the **last** element still throws in `List<T>`: `List<T>.Enumerator.MoveNext()` checks the version before it checks for the end, so the final `MoveNext()` that would have returned `false` throws instead. 3. A change followed immediately by `break` does **not** throw, because no further `MoveNext()` runs. `List<T>.ForEach(Action<T>)` applies the same check and throws after the action that changed the list. ## What does and does not bump the version The interesting part is that collections disagree about which operations count: | Operation during `foreach` | `List<T>` | `Dictionary<TKey,TValue>` (.NET 10) | |---|---|---| | add a new element or key | throws on next `MoveNext` | throws on next `MoveNext` | | `Remove` | throws | **allowed** | | `Clear` | throws | **allowed** (the loop then ends) | | overwrite through the indexer | throws (`list[i] = x` bumps the version) | **allowed** for an existing key | | `EnsureCapacity` that grows the storage | allowed (no version bump) | throws | `Dictionary<TKey,TValue>.Remove` and `Clear` stopped invalidating enumerators in **.NET Core 3.0**; on .NET Framework a `Remove` inside the loop throws. In the .NET 10 source, `HashSet<T>.Remove` and `Clear` likewise leave the version alone, and assigning a new value to a key that already exists in a dictionary does not touch the version either, because no entry moves. Adding a key always bumps it, even right after a `Remove` freed a slot. ## Why removal is safe in a dictionary but not in a list The difference comes from how each type stores its items: - `Dictionary<TKey,TValue>` keeps entries in an array and an enumerator walks that array by index. `Remove` does **not** shift other entries: it marks the removed entry as free (links it into a free list) and leaves every other entry where it was. The enumerator's `MoveNext()` skips free entries. An index that was valid before the removal is still valid after it, so nothing is visited twice or skipped. - `List<T>` keeps elements contiguous. `RemoveAt(i)` shifts every later element one slot left, so an enumerator positioned after `i` would skip the next element. The version check turns that silent skip into an exception. - Adding to a dictionary can resize the arrays or reuse a free slot behind the enumerator's position, so the enumerator could miss the new key or see a moved entry. That is why `Add`, `TryAdd` and inserting a new key through the indexer still bump the version. The example removes `disk` and updates `cpu` and `net` inside one `foreach` without an exception, then shows `TryAdd` throwing on the next `MoveNext()`. Its output is sorted by key, because `Dictionary<TKey,TValue>` does not document an enumeration order. ## What the check is not - **Not thread safety.** The version check catches a change made by the same thread inside its own loop. A second thread writing to a `Dictionary<TKey,TValue>` while another enumerates it can corrupt state or produce wrong results without ever tripping the check. Shared mutable maps belong in `ConcurrentDictionary<TKey,TValue>`, whose enumerator is documented as safe to use alongside concurrent reads and writes, though it is not a moment-in-time snapshot. - **Not a contract to rely on for every collection.** `Queue<T>`, `Stack<T>`, `SortedSet<T>` and `List<T>` invalidate enumerators on structural changes; only the hash-based types relaxed removal. Code that removes while enumerating should name the type it depends on. ## Removal code that does not depend on it When the collection type might change, or the code must also run on .NET Framework, avoid the question entirely: 1. On a `HashSet<T>`, call `RemoveWhere(Predicate<T>)`; on a `List<T>`, call `RemoveAll(Predicate<T>)`. Each removes in one pass with no enumerator involved. 2. On a `Dictionary<TKey,TValue>`, collect the keys to remove into a list during the loop, then remove them after it. 3. Never count on a change being tolerated just because the loop happens to `break` right after it: the next edit to that code can remove the `break`.
- In C#, does adding to a List<T> while processing its last element in foreach throw, given that no further element is visited?Yes. After the body runs, `foreach` calls `MoveNext()` once more to discover the end, and `List<T>.Enumerator.MoveNext()` compares versions before it checks the bounds. The `Add` changed the version, so that final call throws `InvalidOperationException` instead of returning `false`. Only a `break` straight after the change avoids it.
- Does the version check make it safe for another thread to remove entries from a Dictionary<TKey,TValue> that one thread is enumerating?No. The counter is a plain field read without synchronization, and `Dictionary<TKey,TValue>` is not safe for concurrent writes at all; a racing writer can corrupt its buckets or yield wrong results without tripping the check. Use `ConcurrentDictionary<TKey,TValue>`, or a lock around both the loop and the writes.
- Dictionary<TKey,TValue>.Remove inside a foreach over the same dictionary always throws.
- The exception is thrown by the Add or Remove call that changed the collection.
- The version check makes enumerating a Dictionary safe while another thread writes to it.
- Assigning list[i] = x inside a foreach over that List<T> is allowed because nothing is added or removed.
- Since removal is allowed, adding new keys during a dictionary foreach is allowed too.
Assumes .NET 10; Dictionary<TKey,TValue> has tolerated Remove and Clear during enumeration since .NET Core 3.0, while .NET Framework throws.