Introduction

HashMap<String, ...> is case-sensitive by default, so "Key" and "key" are different keys. If you want case-insensitive behavior, the safest general approach is to normalize keys consistently before putting and getting them.

The Simplest Approach: Normalize the Key

Convert all keys to a canonical form such as lowercase with Locale.ROOT.

1import java.util.HashMap;
2import java.util.Locale;
3import java.util.Map;
4
5public class Main {
6    public static void main(String[] args) {
7        Map<String, String> map = new HashMap<>();
8
9        putCaseInsensitive(map, "Content-Type", "application/json");
10        System.out.println(getCaseInsensitive(map, "content-type"));
11        System.out.println(getCaseInsensitive(map, "CONTENT-TYPE"));
12    }
13
14    static void putCaseInsensitive(Map<String, String> map, String key, String value) {
15        map.put(normalize(key), value);
16    }
17
18    static String getCaseInsensitive(Map<String, String> map, String key) {
19        return map.get(normalize(key));
20    }
21
22    static String normalize(String key) {
23        return key.toLowerCase(Locale.ROOT);
24    }
25}

This is simple, predictable, and efficient enough for most applications.

Why Locale.ROOT Matters

Case conversion can vary by locale. If you use toLowerCase() without thinking about locale, some characters can behave unexpectedly in certain regional settings.

That is why normalization code should usually be:

key.toLowerCase(Locale.ROOT)

rather than:

key.toLowerCase()

For stable program logic, Locale.ROOT is the safer default.

Wrap the Behavior in a Dedicated Map

If this pattern appears often, hide it behind a small class so callers do not forget to normalize on lookup.

1import java.util.HashMap;
2import java.util.Locale;
3
4public class CaseInsensitiveMap<V> extends HashMap<String, V> {
5    private static String normalize(Object key) {
6        return key == null ? null : key.toString().toLowerCase(Locale.ROOT);
7    }
8
9    @Override
10    public V put(String key, V value) {
11        return super.put(normalize(key), value);
12    }
13
14    @Override
15    public V get(Object key) {
16        return super.get(normalize(key));
17    }
18
19    @Override
20    public boolean containsKey(Object key) {
21        return super.containsKey(normalize(key));
22    }
23}

Now the case-insensitive rule is enforced in one place.

An Alternative: TreeMap with Case-Insensitive Ordering

If ordering is acceptable, a TreeMap can use a case-insensitive comparator:

1import java.util.Map;
2import java.util.TreeMap;
3
4public class Main {
5    public static void main(String[] args) {
6        Map<String, String> map = new TreeMap<>(String.CASE_INSENSITIVE_ORDER);
7        map.put("Host", "example.com");
8        System.out.println(map.get("host"));
9    }
10}

This is convenient, but it is not a HashMap, and it has different performance and ordering characteristics.

Use it when sorted-map behavior is fine. Use normalization plus HashMap when hash-based storage is what you actually want.

Keep the Original Key or Not

One design question is whether you need to preserve the original letter casing for display. If you normalize keys directly into the map, the original form is lost.

If that matters, store both:

• normalized key for lookup
• original key for presentation

For example, HTTP header maps often need case-insensitive lookup but may still want readable display forms.

What Not to Do

Do not override only put and forget get, containsKey, or remove. That creates a map that is only partially case-insensitive.

Do not rely on callers to remember normalization every time if this behavior is important to correctness. Wrap it in an API or dedicated map type.

Common Pitfalls

Using toLowerCase() without Locale.ROOT can create locale-sensitive surprises.

Normalizing on put but not on get makes the map appear randomly broken depending on the caller's key casing.

Choosing TreeMap without realizing it changes ordering and complexity characteristics can be the wrong tradeoff.

Expecting a regular HashMap<String, ...> to become case-insensitive without an explicit normalization rule is simply incorrect.

Summary

• 'HashMap is case-sensitive by default for string keys.'
• The usual fix is to normalize keys consistently, typically with toLowerCase(Locale.ROOT).
• Wrap normalization logic so callers cannot forget it.
• 'TreeMap with String.CASE_INSENSITIVE_ORDER is an alternative when sorted-map behavior is acceptable.'
• Decide explicitly whether you need to preserve original key casing for display.