Race.NoRace KeyError from running ./example/watch_replay.py

[JonathanNiehenke]

Running the example/watch_replay.py -- Causes KeyError: <Race.NoRace: 0> from .\sc2\bot_ai_internal.py line 754

python .\watch_replay.py

2025-09-23 19:53:09.714 | INFO | sc2.protocol:_execute:75 - Client status changed to Status.in_replay (was None)
2025-09-23 19:53:09.775 | INFO | sc2.protocol:_execute:75 - Client status changed to Status.in_replay (was None)
2025-09-23 19:53:10.023 | INFO | sc2.sc2process:_close_connection:245 - Closing connection at 56194...
2025-09-23 19:53:10.024 | INFO | sc2.sc2process:kill_all:39 - kill_switch: Process cleanup for 1 processes
Traceback (most recent call last):
File "H:\Source\Language\Python\GWiggins\python-sc2\examples\watch_replay.py", line 43, in
run_replay(my_observer_ai, replay_path=str(replay_path))
File "D:\Python39\lib\site-packages\sc2\main.py", line 498, in run_replay
result = asyncio.get_event_loop().run_until_complete(
File "D:\Python39\lib\asyncio\base_events.py", line 642, in run_until_complete
return future.result()
File "D:\Python39\lib\site-packages\sc2\main.py", line 448, in _host_replay
result = await _play_replay(client, ai, realtime)
File "D:\Python39\lib\site-packages\sc2\main.py", line 247, in _play_replay
ai._prepare_step(gs, proto_game_info)
File "D:\Python39\lib\site-packages\sc2\bot_ai_internal.py", line 667, in _prepare_step
self._prepare_units()
File "D:\Python39\lib\site-packages\sc2\bot_ai_internal.py", line 754, in _prepare_units
if unit_id in race_townhalls[self.race]:
KeyError: <Race.NoRace: 0>

[JonathanNiehenke]

A solution is to add:
Race.NoRace: {},
to race_townhalls within ./sc2/data.py

[JonathanNiehenke]

The error originates in commit: 3ae99a9
That changed observer self.race from Race.Random to Race.NoRace within ./sc2/bot_ai_internal.py

[BurnySc2]

In what scenarios is the race set to Race.NoRace?
Are you trying to watch a replay played on an arcade map?

[JonathanNiehenke]

It happens at the beginning of a regular 1v1 replay. In that instance the replay was created using the worker_rush.py example.
The code making the assignment is within ./sc2/bot_ai_internal.py line 630:

# Get the player's race. As observer, get Race.NoRace=0
self.race: Race = Race(self.game_info.player_races.get(self.player_id, 0))

As long as the self.playerId is not in self.game_info.player_races it defaults to Race.NoRace, which is reasonable as an observer is neither a player nor should it have a race.

[JonathanNiehenke]

The sequence for the Race.NoRace assignment are:

run_replay call within watch_replay.py
run_replay calls _host_replay

_host_replay calls play_replay without the optional player_id argument.

python-sc2/sc2/main.py

Line 457 in d0596ce

result = await _play_replay(client, ai, realtime)

So by default player_id = 0 when passed to ai._prepare_start at L245

python-sc2/sc2/main.py

Lines 235 to 246 in d0596ce

	async def _play_replay(client: Client, ai, realtime: bool = False, player_id: int = 0):
	ai._initialize_variables()
	game_data = await client.get_game_data()
	game_info = await client.get_game_info()
	ping_response = await client.ping()
	client.game_step = 1
	# This game_data will become self._game_data in botAI
	ai._prepare_start(
	client, player_id, game_info, game_data, realtime=realtime, base_build=ping_response.ping.base_build
	)

Using the replay from a game of ./examples/worker_rush.py: self.game_info.player_races = {1: 2, 2: 3}
So Race receives the default 0 and self.race = Race:NoRace

python-sc2/sc2/bot_ai_internal.py

Lines 633 to 634 in d0596ce

	# Get the player's race. As observer, get Race.NoRace=0
	self.race: Race = Race(self.game_info.player_races.get(self.player_id, 0))

Conclusion:

As the comment reinforces Race:NoRace seems intentional

[JonathanNiehenke]

To the error:

Continuing within play_replay ai._prepare_step is called
Where prepare_units is called
And within prepare_units we get the KeyError: <Race.NoRace: 0> at L757

python-sc2/sc2/bot_ai_internal.py

Lines 757 to 758 in d0596ce

	if unit_id in race_townhalls[self.race]:
	self.townhalls.append(unit_obj)

race_townhalls is indeed missing Race:NoRace

python-sc2/sc2/data.py

Lines 48 to 72 in d0596ce

	race_townhalls: dict[Race, set[UnitTypeId]] = {
	Race.Protoss: {UnitTypeId.NEXUS},
	Race.Terran: {
	UnitTypeId.COMMANDCENTER,
	UnitTypeId.ORBITALCOMMAND,
	UnitTypeId.PLANETARYFORTRESS,
	UnitTypeId.COMMANDCENTERFLYING,
	UnitTypeId.ORBITALCOMMANDFLYING,
	},
	Race.Zerg: {UnitTypeId.HATCHERY, UnitTypeId.LAIR, UnitTypeId.HIVE},
	Race.Random: {
	# Protoss
	UnitTypeId.NEXUS,
	# Terran
	UnitTypeId.COMMANDCENTER,
	UnitTypeId.ORBITALCOMMAND,
	UnitTypeId.PLANETARYFORTRESS,
	UnitTypeId.COMMANDCENTERFLYING,
	UnitTypeId.ORBITALCOMMANDFLYING,
	# Zerg
	UnitTypeId.HATCHERY,
	UnitTypeId.LAIR,
	UnitTypeId.HIVE,
	},
	}

Solutions?

1. Include Race:NoRace: {} to race_townhalls it probably creates future problems.
2. Because race_worker is also missing Race:NoRace defined just above race_townhalls.
   When prepare_units checks regarding workers
   

   python-sc2/sc2/bot_ai_internal.py

   Lines 778 to 779 in d0596ce

   	if unit_id in worker_types:
   	self.workers.append(unit_obj)

   
   It uses this
   

   python-sc2/sc2/bot_ai_internal.py

   Line 716 in d0596ce

   worker_types: set[UnitTypeId] = {UnitTypeId.DRONE, UnitTypeId.DRONEBURROWED, UnitTypeId.SCV, UnitTypeId.PROBE}

   
   So check a set of all townhalls including their morphs cause as above UnitTypeId.DRONEBURROWED was included.

[BurnySc2]

Would it be possible to override the functions (_prepare_units) in the Observer class instead?

Also have you tried this (old) fix? #138
I'm not sure if it is up to date. However my comment in that PR still stands, as I'd also like to add tests for Github CI to run on the observer interface to know when I or someone else introduce breaking changes to the observer interface.

[JonathanNiehenke]

I will look into overriding _prepare_units.

Running ./example/watch_replay.py from SoupCatcher's commit 6e10320 doesn't error. But that was June 11th 2022 before the Error was introduced in June 27th 2025 in commit 3ae99a9 when it changed observer self.race from Race.Random to Race.NoRace.

-        if self.player_id > 0:
-            self.race: Race = Race(self.game_info.player_races[self.player_id])
-
-            if len(self.game_info.player_races) == 2:
-                self.enemy_race: Race = Race(self.game_info.player_races[3 - self.player_id])
-        else:
-            # Observer
-            self.race: Race = Race.Random
-
-        self._distances_override_functions(self.distance_calculation_method)
+        # Get the player's race. As observer, get Race.NoRace=0
+        self.race: Race = Race(self.game_info.player_races.get(self.player_id, 0))

[JonathanNiehenke]

I don't know about GitHub's CI.
To extend the brainstorm, a reasonable test would be to prove the observer interface sees what a playing-bot saw during the match. A bot could generate a timestamped log of game state as it plays. Like a unit's position, health, energy, upgrades, cooldowns and vision that the accompanying observer-bot checks against while reviewing the replay.
Hopefully, SC2 replays saves the RNG seed and applies it in-replay as it does in-game.