Java HashMap remove: Syntax, Return Values, and Pitfalls
Learn how to remove entries from a Java HashMap, including return values, null handling, iteration safety, performance tradeoffs, and common pitfalls.

Removing entries from a java.util.HashMap is a common operation. The remove method has two overloads: V remove(Object key) and boolean remove(Object key, Object value). The first removes the entry for the given key and returns the previous value, or null if no mapping existed. The second removes the entry only if the key is currently mapped to the specified value, returning true if removal happened.
Understanding the Two remove Overloads
The single-argument overload is the most common. Given a map of user IDs to names, removing a user is straightforward:
Map<Integer, String> users = new HashMap<>();
users.put(1, "Alice");
users.put(2, "Bob");
String removed = users.remove(1); // returns "Alice"The return value is the value that was associated with the key before removal. If the key was absent, remove returns null. This is useful when you need to know whether a mapping actually existed, but be careful: if the map legitimately contains null values, a null return does not distinguish between "no mapping" and "mapped to null". To check existence before removal, use containsKey or the two-argument overload.
The two-argument overload, added in Java 8, removes the entry only if the key is currently mapped to the given value:
boolean removed = users.remove(2, "Bob"); // true, removes entry
boolean notRemoved = users.remove(2, "Alice"); // false, key absent or value mismatchThis overload combines the mapping check and removal in one method call, so you do not need a separate containsKey check followed by remove. That avoids a check-then-act race in code where the map is otherwise accessed safely. On a plain HashMap, it is not a substitute for synchronization if multiple threads can modify the map; ConcurrentHashMap provides the same conditional removal atomically.
How remove Handles Null Keys and Values
HashMap permits one null key and any number of null values. The remove method handles these without special logic. For a null key, remove(null) will remove the entry if it exists. For values, the two-argument overload uses Objects.equals to compare, so null is handled correctly.
Map<String, String> map = new HashMap<>();
map.put(null, "nullKey");
map.put("key", null);
String v1 = map.remove(null); // returns "nullKey"
boolean v2 = map.remove("key", null); // true, because value is nullA common mistake is to assume that remove returns null only when the key is absent. If the key was mapped to null, the return value is also null, so you cannot distinguish the two cases without containsKey. The two-argument overload avoids this ambiguity because it returns a boolean.
Removing Entries Safely During Iteration
Iterating over a HashMap while calling remove directly on the map causes a ConcurrentModificationException in most cases. The fail-fast iterator detects structural modification and throws on a subsequent next() call.
// This can throw ConcurrentModificationException
for (String key : map.keySet()) {
if (key.startsWith("temp")) {
map.remove(key);
}
}To remove entries during iteration, use the iterator's own remove method. The iterator is aware of the modification and updates its internal state correctly.
Iterator<String> it = map.keySet().iterator();
while (it.hasNext()) {
String key = it.next();
if (key.startsWith("temp")) {
it.remove();
}
}The same pattern works for entrySet() and values(). If you need to remove based on both key and value, use entrySet().iterator() and inspect the Map.Entry.
Java 8 introduced Collection.removeIf, which is a more concise alternative for conditional removal:
map.keySet().removeIf(key -> key.startsWith("temp"));removeIf is implemented as a default method on Collection that uses an iterator internally, so it does not cause the iterator to see its own removals as concurrent changes. It is often the clearest way to express a bulk removal condition.
Performance Characteristics of remove
The average time complexity of remove is O(1), assuming a well-distributed hash function and a load factor below the threshold. The operation computes the key's hash, locates the bucket, and removes the node. In the worst case, when many keys collide into the same bucket, the cost can degrade to O(n) for that bucket, but this is rare with a proper hashCode implementation.
Removing an entry does not shrink the backing array. HashMap has no trimToSize method and does not shrink automatically as entries are removed. If you remove many entries and want to release memory, build a new HashMap from the remaining entries.
When using the two-argument overload, the lookup is the same O(1), but it also compares the current value with the given value using Objects.equals. That comparison is usually cheap, but if the value type has an expensive equals method, the removal operation becomes proportionally slower.
Comparing remove, clear, and removeIf
clear() removes all entries in one call. It clears the backing array, so its cost is proportional to the table capacity rather than the number of entries. It is still far more efficient than calling remove in a loop for every key. Use clear when you want to reset the map entirely.
removeIf is best for conditional bulk removal based on a predicate. It is implemented as a default method on Collection and works on the key set, value collection, or entry set. It is more readable than an explicit iterator loop and avoids the risk of ConcurrentModificationException.
The single-key remove is the right choice when you know exactly which key to delete. It is simple, fast, and returns the previous value if you need it. The two-argument overload is useful when you want to ensure that you are removing the expected mapping, especially in concurrent or multi-threaded scenarios where a key might have been reassigned.
| Method | Scope | Return Type | Use Case |
|---|---|---|---|
remove(key) | Single entry | V | Delete by key, get previous value |
remove(k, v) | Single entry | boolean | Delete only if key maps to specific value |
removeIf(...) | Multiple | boolean | Delete entries matching a condition |
clear() | All entries | void | Reset the map entirely |
Common Pitfalls with Mutable Keys
If a key object's hashCode changes after it is inserted into the map, the entry will be stored in the wrong bucket. Calling remove with that key will likely fail because the lookup uses the current hash to find the bucket, which no longer matches the bucket where the entry lives. The entry remains in the map but is no longer findable by normal lookup, so it can effectively leak memory.
class MutableKey {
int id;
MutableKey(int id) {
this.id = id;
}
// hashCode and equals are based on id
}
Map<MutableKey, String> map = new HashMap<>();
MutableKey key = new MutableKey(1);
map.put(key, "value");
key.id = 2; // hashCode changes
map.remove(key); // may not find the entryTo avoid this, use immutable keys or never modify fields that contribute to hashCode after insertion. If you must mutate a key, remove it first, then mutate, then reinsert.
Choosing the Right Removal Approach
The decision among remove(key), remove(key, value), removeIf, and clear depends on the exact requirement. Use remove(key) when you have the key and need the previous value. Use remove(key, value) when you need conditional removal to avoid overwriting a newer mapping. Use removeIf for bulk deletion based on a predicate, and clear when you want to empty the map entirely.
For iteration-based removal, always prefer Iterator.remove() or removeIf over direct map.remove() to avoid ConcurrentModificationException. The iterator approach is explicit and works on all Java versions; removeIf is more concise and available since Java 8.
In concurrent environments, none of these methods are thread-safe on a plain HashMap. If multiple threads modify the map, use ConcurrentHashMap, which provides atomic remove operations and weakly consistent iterators. The remove(key, value) overload on ConcurrentHashMap is especially useful for conditional removal without external synchronization.
Try matching browser tools
All toolsSmall utilities that fit Java work — they run entirely in this browser tab, so nothing you paste leaves your device.
Related Java guides
All Java guidesJava Final Keyword: Usage and Behavior
How Java's final keyword works for variables, methods, and classes, with practical examples and decision guidance for using it.
Java Final Variable: Syntax, Behavior, and Use Cases
Understand what a final variable in Java means, how initialization works, and when to use it for constants, immutability, and clearer code.
Java Duration vs Period: When to Use Each
java duration vs period: Compare Java Duration and Period to handle time-based and date-based calculations correctly. Learn syntax, conversion, and pitfalls.
Instance vs Static Variables in Java: Key Differences
Understand the difference between instance and static variables in Java, including memory, lifecycle, and when to use each.
More in Java
All Java guidesThe guides filed next to this one in Java, in library order.