Quick answer: in Unreal, Map[Key] does not add a missing key the way std::map does. If the key isn’t there, it asserts and the editor stops. Use instead:
- Read if it exists:
Findreturns a pointer, ornullptrif the key is missing. - Read with a fallback:
FindRefreturns a copy, or a default value. - Read or create:
FindOrAddreturns a reference and adds the key if it’s missing. - Only check:
Containsreturnstrueorfalse.
Only use operator[] when you’re certain the key is in the map.
Why operator[] crashes
TMap::operator[] looks up the key and expects to find it. Epic’s documentation puts it plainly: if the map doesn’t contain the key, it asserts. In the editor and Development builds you get an assertion failure. In a Shipping build the check is compiled out and the game crashes instead.
That’s the opposite of the C++ standard library, where std::map[Key] silently inserts a default value. Code ported from std::map is the most common way to hit this.
Which function to use
| You want to… | Use | Returns | Adds a missing key? |
|---|---|---|---|
| Read a value only if it exists | Find(Key) | Pointer, or nullptr | No |
| Read a value or get a default | FindRef(Key) | Copy of the value | No |
| Read or create the value | FindOrAdd(Key) | Reference | Yes, default-constructed |
| Check whether a key exists | Contains(Key) | bool | No |
| Set a value (insert or overwrite) | Add(Key, Value) | Reference to the stored value | Yes |
| Read a key you know exists | Map[Key] | Reference | No, asserts if missing |
Read safely with Find
Find does the check and the read in one lookup:
int32* Score = Scores.Find(PlayerName);
if (Score)
{
*Score += 10;
}
Contains followed by Map[Key] works too, but it searches the map twice.
Write without crashing
Use Add to set a value. It inserts the key, or replaces the value if the key is already there:
Scores.Add(PlayerName, 0);
For counters, FindOrAdd reads or creates in one call:
Scores.FindOrAdd(PlayerName) += 10;
Map[Key] = Value; only works when the key already exists. It doesn’t add new keys.
Gotchas
Don’t keep pointers or references across Add or Remove. The pointer from Find and the reference from FindOrAdd or operator[] can become invalid when the map adds or removes elements. Look the value up again after changing the map.
FindOrAddisn’t available on aconstmap. UseFindorFindRefthere.FindRefreturns a copy, so changing the result doesn’t change the map.- In Blueprints, the Map Find node never crashes. It returns the value and a Found boolean.
FAQ
How do I check if a key exists in a TMap?
Map.Contains(Key) returns a bool. If you also need the value, Map.Find(Key) returns a pointer you can test for nullptr.
Does FindRef add the key?
No. It returns a copy of the value, or a default-constructed value if the key is missing, and leaves the map unchanged.
Is operator[] faster than Find?
No. Both do one lookup. operator[] just skips the null check and asserts instead.
Why does my map crash only in a packaged game?
A Map[Key] with a missing key asserts in the editor. If that code path only runs in the packaged game, you only see the crash there. Replace it with Find or FindOrAdd.